Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d7 / boyan5b.arc / BOYAN.DOC < prev next >

Wrap

Text File | 1991-05-28 | 401KB | 8,733 lines

=========== BOYAN Registration Form ============ Version 5.0 =========== Phone orders: BBS orders: (301)-805-7168 (301)-730-2917 ------------------------------------------------------------------------ Remit to: Justin Boyan BOYAN COMMUNICATIONS P.O. Box 71 Woodstock, MD 21163 ------------------------------------------------------------------------ Please send: _____ BOYAN registration . . . . . . . . . . . . .ea $40.00 = $ _______ _____ BOYAN registration & 5.25" disks . . . . . .ea $60.00 = $ _______ (includes two floppy disks, program, manual, and Quick Ref card) _____ BOYAN registration & 3.5" disk . . . . . . .ea $60.00 = $ _______ (includes one 720K disk, program, manual, and Quick Ref card) Subtotal = $ _______ Please add 15% if check is not U.S. currency . . . . . $ _______ Shipping and handling . . . . . . . . . . . included = $ 0.00 Total = $ _______ ------------------------------------------------------------------------ Check enclosed [ ] OR Mastercard [ ] VISA [ ] Card Number ____________________________ Expiration date ________ ------------------------------------------------------------------------ Name: _______________________________________________________________ Company: _______________________________________________________________ Address: _______________________________________________________________ _______________________________________________________________ ======================================================================== BOYAN Communications Version 5 Professional User-Supported Communications Software USER'S MANUAL Copyright (C) 1986,1987,1989,1991 BOYAN Communications P.O. Box 71 Woodstock, MD 21163 Phone orders: (301)-805-7168 Support BBS: (301)-730-2917 RIME Network Forum #118 SPECIAL THANKS Bonnie Anthony Ed Bachmann Kitty & Steve Boyan Lee Breeden Bruce Felstein Lyle Giuse Jim Luhman Kelly McGraw John Navas Jim Provan Kent Stromsmoe Dennis Tuchler Tom Vervaeke Erik Winfree Cover artwork by Jeff Hesser All brand and product names are trademarks or registered trademarks of their respective holders. Copyright (C) 1986-91, Justin Boyan All rights reserved ii Contents Chapter 1 Introduction 1 1.1 What Makes BOYAN Special? . . . . . . . . . . . . . . 1 1.1.1 Flexibility . . . . . . . . . . . . . . . . . . . 1 1.1.2 Features . . . . . . . . . . . . . . . . . . . . 2 1.1.3 Ease of Use . . . . . . . . . . . . . . . . . . . 3 1.2 Licensing Agreement . . . . . . . . . . . . . . . . . 4 1.2.1 How to Order . . . . . . . . . . . . . . . . . . 5 1.2.1.1 Order by Mail . . . . . . . . . . . . . . . . 5 1.2.1.2 Order by Phone . . . . . . . . . . . . . . . 5 1.2.1.3 Order by BBS . . . . . . . . . . . . . . . . 5 1.2.2 Corporate Licenses . . . . . . . . . . . . . . . 5 1.2.3 Distribution of BOYAN . . . . . . . . . . . . . . 6 1.3 Support for Registered Users . . . . . . . . . . . . 7 1.4 Disclaimer . . . . . . . . . . . . . . . . . . . . . 7 1.5 Using This Manual . . . . . . . . . . . . . . . . . . 7 Chapter 2 Getting Started with BOYAN 9 2.1 System Requirements . . . . . . . . . . . . . . . . . 9 2.2 Setting BOYAN Up On Disk . . . . . . . . . . . . . . 9 2.2.1 Files Included with BOYAN . . . . . . . . . . . 10 2.3 Running BOYAN for the First Time . . . . . . . . . 11 2.3.1 Running BOYAN . . . . . . . . . . . . . . . . . 11 2.3.2 First-time Modem Setup . . . . . . . . . . . . 11 2.3.3 BOYAN under Microsoft Windows . . . . . . . . . 12 2.3.4 BOYAN under DesqView . . . . . . . . . . . . . 12 2.4 The World of BOYAN . . . . . . . . . . . . . . . . 12 2.4.1 The Status Line . . . . . . . . . . . . . . . . 12 2.4.2 <Esc> = Go Back . . . . . . . . . . . . . . . . 13 2.4.3 The Help System . . . . . . . . . . . . . . . . 13 2.4.4 Using a Mouse . . . . . . . . . . . . . . . . . 13 2.4.5 The Line Editor . . . . . . . . . . . . . . . . 14 Chapter 3 <Alt-C> Customizing BOYAN 16 3.1 Configuring a Non-Hayes-Compatible Modem . . . . . 17 3.2 Configuring a Nonstandard Comm Device . . . . . . . 17 3.3 Configuring a Two-Floppy System . . . . . . . . . . 18 3.4 Configuring a High-Speed Modem . . . . . . . . . . 18 3.5 Config Area <S> -- Screen, Sound, Memory . . . . . 19 3.6 Config Area <D> -- Disk and File Setup . . . . . . 21 iii 3.7 Config Area <C> -- Communications options . . . . . 24 3.8 Config Area <E> -- Expert Communications Options . 26 3.9 Config Area <M> -- Macros . . . . . . . . . . . . . 28 3.9.1 Basic Macro Commands . . . . . . . . . . . . . 28 3.9.2 The 120 BOYAN Macros . . . . . . . . . . . . . 29 3.9.3 Modem Dialing & Auto-macros . . . . . . . . . . 30 3.9.4 <Alt-K> Function Key Customization . . . . . . 32 3.10 Config Area <A> -- BOYAN Action Modules . . . . . 33 3.10.1 BAM Selection . . . . . . . . . . . . . . . . 33 3.10.2 Terminal Emulation Configuration . . . . . . . 34 3.10.3 Host Mode Configuration . . . . . . . . . . . 34 3.11 Config Area <T> -- Translation/filter table . . . 35 3.12 Config Area <X> -- External File Transfer Protocols . . . . . . . . . . . . . . . . . . . . 36 3.12.1 Auto-downloading . . . . . . . . . . . . . . . 38 Chapter 4 BOYAN Command Capabilities 39 4.1 Basic Commands . . . . . . . . . . . . . . . . . . 39 4.1.1 <F1> Help Menu . . . . . . . . . . . . . . . . 39 4.1.2 <Alt-F1> Function Key Menu . . . . . . . . . . 39 4.1.3 <Alt-B> Beeps & Bells Toggle . . . . . . . . . 40 4.1.4 <Alt-E> Echo Keyboard Toggle . . . . . . . . . 40 4.1.5 <Alt-G> 43/50-Line Mode . . . . . . . . . . . . 40 4.1.6 <Alt-O> Restore Default Text Color . . . . . . 40 4.1.7 <Alt-T> Translation Table Toggle . . . . . . . 40 4.1.8 <Alt-X> Exit BOYAN . . . . . . . . . . . . . . 40 4.1.9 <Alt-Z> Zap (Clear) Screen . . . . . . . . . . 41 4.1.10 <Shift-Tab> Add Linefeeds Toggle . . . . . . . 41 4.2 Modem Commands . . . . . . . . . . . . . . . . . . 41 4.2.1 <Alt-D> Dial a System . . . . . . . . . . . . . 41 4.2.1.1 Manual Dialing . . . . . . . . . . . . . . 41 4.2.1.2 Code Number Dialing . . . . . . . . . . . . 42 4.2.1.3 After Dialing . . . . . . . . . . . . . . . 42 4.2.1.4 Dialing Directory Options . . . . . . . . . 43 4.2.1.5 Long-Distance Dialing Prefixes . . . . . . 48 4.2.1.6 Uniform Dialing Prefixes . . . . . . . . . 48 4.2.1.7 Disable Call Waiting . . . . . . . . . . . 49 4.2.2 <Alt-H> Hang Up Modem . . . . . . . . . . . . . 49 4.2.3 <Alt-P> Parameter Change . . . . . . . . . . . 49 4.2.4 <Alt-Q> Queue Redialing . . . . . . . . . . . . 50 4.2.5 <Ctrl-End> Send Modem Break Signal . . . . . . 52 4.2.6 <Del> Send DEL character . . . . . . . . . . . 52 4.3 BOYAN Action Modules . . . . . . . . . . . . . . . 52 4.3.1 <Alt-A> Activate new Action Module . . . . . . 52 4.3.2 <Alt-Equals> Previous Action Module . . . . . . 52 4.3.3 <Scroll-Lock> Switch Between BOYAN/Terminal Keysets . . . . . . . . . . . . . . . . . . . . 53 4.3.4 Action Module Descriptions . . . . . . . . . . 53 iv 4.3.4.1 ADM-3A, IBM-3101, TVI-925, and VT-52 Emulations . . . . . . . . . . . . . . . . 53 4.3.4.2 ANSI-BBS Emulation . . . . . . . . . . . . 53 4.3.4.3 CONTROL Action Module . . . . . . . . . . . 53 4.3.4.4 DOORWAY Module . . . . . . . . . . . . . . 54 4.3.4.5 DUMBTERM (Dumb Terminal) . . . . . . . . . 54 4.3.4.6 GOSSIP Mode . . . . . . . . . . . . . . . . 54 4.3.4.7 HOST Action Module . . . . . . . . . . . . 54 4.3.4.8 VT-100 Emulation . . . . . . . . . . . . . 54 4.4 BOYAN File Transfers . . . . . . . . . . . . . . . 55 4.4.1 Internal Protocols . . . . . . . . . . . . . . 55 4.4.2 External Protocols . . . . . . . . . . . . . . 56 4.4.3 Auto-Find Filename Feature . . . . . . . . . . 57 4.4.4 <PgUp> Upload File . . . . . . . . . . . . . . 58 4.4.5 Uploading a Message . . . . . . . . . . . . . . 58 4.4.6 <PgDn> Download File . . . . . . . . . . . . . 59 4.5 Session Logging . . . . . . . . . . . . . . . . . . 60 4.5.1 <Alt-L> Log to Disk Toggle . . . . . . . . . . 60 4.5.2 <Alt-S> Save Screen Image to Disk . . . . . . . 60 4.5.3 <Alt-U> Toggle BOYAN.USE Usage Log File . . . . 61 4.5.4 <Ctrl-PrtSc> Printer Log Toggle . . . . . . . . 61 4.5.5 <Shift-PrtSc> Save Screen Image to Printer . . 61 4.6 DOS and File Commands . . . . . . . . . . . . . . . 61 4.6.1 <Alt-F> The File Manager . . . . . . . . . . . 61 4.6.2 <Alt-J> Jump to DOS . . . . . . . . . . . . . . 64 4.6.3 <Alt-N> New Default Drive/Directory . . . . . . 65 4.6.4 <Alt-V> View File . . . . . . . . . . . . . . . 65 4.6.5 <Alt-W> Word Process (Edit) File . . . . . . . 65 4.6.6 <Alt-Y> Free Space on Disk . . . . . . . . . . 65 4.6.7 <Ins> Issue DOS Command . . . . . . . . . . . . 65 4.7 Scroll-Back Buffer, Scripts, etc. . . . . . . . . . 66 4.7.1 <Alt-R> Run Script File . . . . . . . . . . . . 66 4.7.2 <UpArrow> Scroll-Back Buffer . . . . . . . . . 66 4.7.3 Script Learn Facility . . . . . . . . . . . . . 68 4.7.3.1 Example: Auto-Logon Scripts . . . . . . . . 68 4.7.3.2 Password Security Feature . . . . . . . . . 70 4.7.3.3 Details on Script Learning . . . . . . . . 70 4.7.4 <Alt-M> Enter Macro Manually . . . . . . . . . 71 4.8 BOYAN's Host Mode . . . . . . . . . . . . . . . . . 71 4.8.1 Preliminaries . . . . . . . . . . . . . . . . . 72 4.8.2 <Alt-I> Invoking Host Mode . . . . . . . . . . 73 4.8.3 Using the Host . . . . . . . . . . . . . . . . 73 4.8.4 Host User Command Menu . . . . . . . . . . . . 74 4.8.5 Local Sysop Menu . . . . . . . . . . . . . . . 75 4.8.6 Customizing HOST.BSC . . . . . . . . . . . . . 77 4.9 BOYAN's Backspace Editor . . . . . . . . . . . . . 78 4.9.1 <Backspace> Erase Previous Character . . . . . 78 4.9.2 <LeftArrow> Forget Previous Character . . . . . 78 4.9.3 <Ctrl-Backspace> Erase Previous Word . . . . . 78 v 4.9.4 <Ctrl-LeftArrow> Forget Previous Word . . . . . 78 4.9.5 <RightArrow> Un-erase Character . . . . . . . . 78 4.9.6 <Ctrl-RightArrow> Un-erase Word . . . . . . . . 78 4.9.7 Using the Backspace Editor . . . . . . . . . . 78 Chapter 5 BOYAN Power--Macros and Script Files 80 5.1 Overview . . . . . . . . . . . . . . . . . . . . . 80 5.2 The Macro Programming Language . . . . . . . . . . 80 5.2.1 String Output . . . . . . . . . . . . . . . . . 81 5.2.2 How to Read the Macro Definitions . . . . . . . 81 5.2.2.1 Conditional Macro Syntax . . . . . . . . . 82 5.2.3 Modem Commands . . . . . . . . . . . . . . . . 82 5.2.4 Terminal Characteristics . . . . . . . . . . . 84 5.2.5 Backspace Buffer . . . . . . . . . . . . . . . 85 5.2.6 Timing . . . . . . . . . . . . . . . . . . . . 86 5.2.7 Handshaking . . . . . . . . . . . . . . . . . . 86 5.2.8 Dialing . . . . . . . . . . . . . . . . . . . . 88 5.2.9 Queue Redialing . . . . . . . . . . . . . . . . 89 5.2.10 Screen & Sound . . . . . . . . . . . . . . . . 90 5.2.11 Session Logging & Printing . . . . . . . . . . 93 5.2.12 DOS . . . . . . . . . . . . . . . . . . . . . 94 5.2.13 File Transfers . . . . . . . . . . . . . . . . 96 5.2.14 User Variables . . . . . . . . . . . . . . . . 98 5.2.15 Macro Control . . . . . . . . . . . . . . . . 100 5.2.16 Miscellaneous . . . . . . . . . . . . . . . . 102 5.2.17 <Shift-F1> Trace Mode . . . . . . . . . . . . 103 5.3 BOYAN Macro Tutorial, Examples . . . . . . . . . . 104 5.3.1 Built-in Keystroke Examples . . . . . . . . . . 104 5.3.2 Auto-macro Examples . . . . . . . . . . . . . . 106 5.3.3 Yet More Key Examples! . . . . . . . . . . . . 108 5.4 The BOYAN Command Line . . . . . . . . . . . . . . 110 5.5 Script Files . . . . . . . . . . . . . . . . . . . 111 5.5.1 Script-specific Macro Commands . . . . . . . . 111 5.5.2 Automatic Logon Scripts . . . . . . . . . . . . 112 5.5.3 Running Script Files . . . . . . . . . . . . . 113 5.5.4 During Script Execution . . . . . . . . . . . . 114 5.5.5 Script Examples . . . . . . . . . . . . . . . . 114 5.5.6 Technical Notes . . . . . . . . . . . . . . . . 115 5.5.6.1 The Macro Compiler . . . . . . . . . . . . 115 5.5.6.2 Variable Prefixes: % vs. @ . . . . . . . . 116 5.6 Summary of Macro Variables . . . . . . . . . . . . 117 5.7 Summary of Macro Commands . . . . . . . . . . . . . 120 Appendix A HELP! Common Questions & Answers 133 A.1 Modem Questions . . . . . . . . . . . . . . . . . . 133 A.2 DOS Questions . . . . . . . . . . . . . . . . . . . 134 A.3 BAM Questions . . . . . . . . . . . . . . . . . . . 134 A.4 File Transfer Questions . . . . . . . . . . . . . . 135 A.5 Macro Questions . . . . . . . . . . . . . . . . . . 136 vi A.6 Miscellaneous . . . . . . . . . . . . . . . . . . . 136 Appendix B BOYAN Error Messages 137 Appendix C Glossary of BOYAN Terms 138 Appendix D The VT-100 Secondary Keyset 140 D.1 Default Key Layout . . . . . . . . . . . . . . . . 140 D.2 Customization . . . . . . . . . . . . . . . . . . . 141 Index 143 vii Chapter 1 Introduction 1.1 What Makes BOYAN Special? When BOYAN Communications was first released in 1986, it set a new standard for PC communications software. Now in its fifth major revision, BOYAN perfects the features that made it famous: - A clean, consistent, and friendly interface. One user compared using BOYAN to driving a luxury sports car. - Innovative, powerful features. PC Magazine once wondered "why nobody else thought of them." - Above all, a philosophy: if something is boring, then the computer should do it for you. Once you try BOYAN 5... there's no looking back! 1.1.1 Flexibility - BOYAN supports interrupt-driven communications with all serial ports and modems, at speeds from 300 to 38,400 baud. Both hardware and software flow control are supported for high-speed modems and networking. - BOYAN Action Modules allow BOYAN to emulate popular terminals, including VT-100, VT-52, TVI-925, IBM-3101, ADM-3A, and ANSI-BBS. Terminal emulations use their own "secondary" keysets which can easily be customized. Further emulations, as they are developed, can be easily installed into BOYAN 5. - Speedy, reliable file transfers use a wide variety of common error- checking protocols, including Xmodem, CRC-Xmodem, Ymodem, 1K-Xmodem, Ymodem-G, 1K-Xmodem-G, ASCII, Kermit, Ymodem-batch, and Zmodem. Additional protocols can easily be integrated into BOYAN, too. Hands-free "auto-downloading" is provided for any protocol that supports it, including Zmodem, Bimodem, and MPt. 1.1.1: Introduction 2 ________________________________________________________________________ - An extensive macro language with over 300 commands and variables can automate all your communication needs: * All of BOYAN's command keys are user-definable; thus, you can customize BOYAN's keyboard layout to exactly your own preferences. (See section 5.3 for many useful examples.) * Auto-macros give you total control over what BOYAN does when initializing, dialing, connecting, or hanging up your modem. * Shortcut macros allow common passwords and long-distance dialing prefixes to be stored and used easily. * BOYAN script files can run communications sessions completely unattended, supporting: handshaking, timing, conditional execution, block nesting, macro nesting, and much more. * BOYAN's Script Learn feature remembers what you type at all times. After a session, BOYAN can walk you through what you typed and build an automatic script file for you. You may edit the script before it is saved, so that your next session on that system is hands-free! * Sample script files are provided for streamlining your use of CompuServe and common Bulletin Board Systems. * A simple "trace mode" helps you follow even the most sophisticated macros and scripts. - BOYAN provides a Host Mode which allows you to dial in to your computer from a remote system, read and write messages, send and receive files, and run programs remotely. A built-in database holds the name, password, and user level for up to 70 users. Furthermore, since the Host Mode is written as a BOYAN script, it is fully customizable. 1.1.2 Features - With BOYAN's famous automatic filename entry feature, you never again have to type a filename twice before downloading a file. - BOYAN saves you time and money by allowing you to upload messages you have prepared off-line. Exclusive: BOYAN determines the line prompt character and handles awkward "word wraps." - A usage log records the length of all modem connections and the efficiency of all file transfers for later reference. This log can verify your phone records, for example. 1.1.2: Introduction 3 ________________________________________________________________________ - BOYAN works with DOS at all times: * Issuing any DOS command, running any program, and entering DOS temporarily are possible during a communication session. * BOYAN uses your favorite file lister and word processor/editor. * A full, built-in File Manager allows you to scan disk directories, copying and viewing files at the touch of a key. Select files for uploading as well as BOYAN script files directly from the File Manager listing. - Dialing directories maintain the names, numbers, parameters, Action Module, logon script, file transfer protocol, password, and last connect date for all the systems you ever need to dial. Editing, sorting, searching, and printing a directory can all be done within BOYAN. Phone numbers can be automatically "grabbed" from the terminal screen, making it easy to add to your dialing directory. Multiple dialing directories allow you to organize your phone lists any way you want. - A 20-number dynamic redialing queue stores the numbers which you dial but fail to connect. If you wish, BOYAN automatically redials each of the numbers in turn, showing the status of each system in a full- screen display. Numbers may be added to and deleted from the queue at any time. - A scroll-back buffer stores hundreds of lines of text which has scrolled off the top of the screen. Within the buffer, you can locate specific strings, mark passages to be printed or filed to disk, and automatically move to the beginning of the current session. - A Gossip Action Module splits the screen into "local" and "remote" windows, allowing clear on-line conversations between two modem users. - The Doorway Action Module makes it possible to run any non-graphics program remotely, over the modem. 1.1.3 Ease of Use - Context-sensitive help screens are available at all times with the <F1> key. - "Back up" or cancel the current action anytime with the <Esc> key. - BOYAN offers full mouse support. 1.1.3: Introduction 4 ________________________________________________________________________ - A status line keeps you informed of the currently-connected system, the elapsed time of the call, and the script file in control. - BOYAN's Line Editor facilitates entering and editing responses to BOYAN prompts. - With BOYAN's exclusive backspace editor, typing errors can be quickly corrected without retyping any erased words. You can delete by word, not just character-by-character. Text can be inserted or deleted on a line at any time. - Configurable filter tables, screen dumps, disk logging, printer log- ging, automatic modem speed-detection, break signal support, and many other options make BOYAN superior for any kind of microcomputer communications. 1.2 Licensing Agreement BOYAN Communications is Copyright (C) 1986-1991 by Justin Boyan, P.O. Box 71, Woodstock, MD 21163. BOYAN Communications is not free software. BOYAN is made publicly available only to allow users to preview BOYAN on a trial basis. Any use of BOYAN beyond this limited purpose requires registration as de- scribed below. Use of unregistered copies of BOYAN Communications by any individual, business, corporation, government agency, or other institution is prohibited. Registration of BOYAN Communications entitles you to use BOYAN on a regular basis. By registering your copies of BOYAN: - You support the ShareWare concept of marketing, which allows you to "try before you buy" and encourages lower prices for all software; - You receive written registration confirmation and a BOYAN User ID; - You receive a code number which modifies Boyan to bypass the "Press <Enter> to continue" screen and other ShareWare messages; - You are entitled to priority support on the BOYAN Support BBS; - You are automatically registered for any future releases of BOYAN, and you will receive mailed announcements of major upgrades. 1.2.1: Introduction 5 ________________________________________________________________________ 1.2.1 How to Order The complete BOYAN package, including registration, typeset manual, convenient Quick Reference Card, and the latest version on your choice of 5.25'' or 3.5'' diskettes costs only $60.00. If you do not wish to receive the manual, Quick Reference Card, or diskettes, then the registration charge is $40.00. Terrific site licensing discounts are described below in section 1.2.2. All domestic orders will be shipped by UPS, except those to P.O. box addresses, which will be shipped at book rate (4th class). Overseas orders will be shipped by air, small packet rate. 1.2.1.1 Order by Mail To order by mail, please use the order form at the beginning of this manual, and enclose a check or money order made out to "Boyan Communications". If payment is not in U.S. currency, please add 15% to cover conversion costs. 1.2.1.2 Order by Phone To order by VISA or Mastercard, call the BOYAN order line anytime at (301)-805-7168. 1.2.1.3 Order by BBS You may also order directly from the BOYAN Support Bulletin Board System. To do this, log on to the BOYAN Support BBS at (301)-730-2917. When you reach the main menu, simply enter the command REGISTER. You will be prompted to type your name, address, phone, and VISA or Mastercard number. Your order will be filled as soon as we can verify your credit card. 1.2.2 Corporate Licenses A registered copy of BOYAN may be used on only one computer at a time; it may not be copied for use on multiple computers at a time. To encourage corporations to register their usage of BOYAN ethically, we offer large discounts on registration of multiple copies. Use the following chart to determine the licensing cost for your needs: If you need... Then registration costs: 1-6 copies $ 40 each up to 15 copies $250 flat fee up to 50 copies $500 flat fee unlimited site license $750 flat fee 1.2.2: Introduction 6 ________________________________________________________________________ - An institution wishing a site license should appoint one contact person to handle BOYAN's registration, support questions, and update notices. - Any site license (seven or more copies) entitles you to a custom version of BOYAN with your company name on the welcome screen. - Two copies of the BOYAN package (User's Manual, Quick Reference card, and disks) are included with any site license. Additional packages are available for the regular price of $20 each. - Corporate purchase orders will be accepted on any order of $60.00 or more. 1.2.3 Distribution of BOYAN In accordance with the ShareWare distribution method, all users are granted permission to copy BOYAN Communications for the trial use of others, providing the following conditions are met: - BOYAN must be copied in completely unmodified form, and distributed together with the full and unmodified documentation and licensing information. - You may not sell or trade BOYAN for money or any valuable consid- eration, except for a nominal charge for postage, handling, and materials. - BOYAN may not be distributed in conjunction with any other product, hardware or software, without the express written consent of BOYAN Communications. Failure to abide by this limited license by sale or modification of BOYAN Communications is a violation of the U.S. Copyright Act. Electronic Bulletin Board Systems, Public PC Users Groups and clubs may add BOYAN to their ShareWare libraries subject to the conditions above. In addition, BOYAN Communications is offering a special 50% User Group discount on version 5 registrations. Club librarians, please write for further information! ShareWare distributors may add BOYAN Communications to their libraries subject to the conditions above, only after writing for and receiving my written consent. It must be stated prominently that 1) BOYAN is ShareWare, 2) the disks you send are for evaluation use only, and 3) the BOYAN registration fee of $40.00 is payable directly to the author. 1.3: Introduction 7 ________________________________________________________________________ 1.3 Support for Registered Users BOYAN support is provided on the international RIME network of Bulletin Board Systems, in Forum #118. The home BBS for this forum is located in Columbia, Maryland at (301)-730-2917. This BBS will give you full access to the BOYAN message and file areas on your first call: just register as a new user, proceed to the main menu, and enter the command J BOYAN. At that point, you may use the E command to enter a new message. Support questions should be addressed to "ALL" and "echoed" throughout the network. This BBS also offers the command RIME xxx-- where xxx is your area code--to obtain a list of RIME network BBS'es in your local area code which may carry the BOYAN forum. If you prefer, you may mail questions directly to Boyan Communications, P.O. Box 71, Woodstock, MD 21163. Please include your BOYAN ID registration number if you write for support. 1.4 Disclaimer Justin Boyan and BOYAN Communications make no warranty, expressed or implied, concerning this program's merchantability or fitness for any particular use. In no event is Justin Boyan or BOYAN Communications liable to you for any damages resulting from your use of the program. 1.5 Using This Manual BOYAN 5 is an easy program to use. Its commands are mnemonic and consistent, and on-line help screens are available at any time by pressing <F1>. Experienced users and new users alike will be able to use BOYAN effectively without ever reading this manual. The help screens, however, summarize rather than fully explain BOYAN's features. The complete information is here. If you try each command on your PC as it is described, you will realize the full power of BOYAN. This manual also provides several helpful appendices: "Common Questions & Answers," "BOYAN error messages," and "A Glossary of BOYAN Terms." When something goes wrong, you're likely to find help there! Please note the following typographical conventions: - Text in brackets, such as <Esc>, indicates a key for you to press. When entering a key combination such as <Ctrl-PgUp>, hold down the first key and then hit the second. 1.5: Introduction 8 ________________________________________________________________________ - A word whose first letter is underlined, like This, represents a command which you can select by pressing that letter (in this case T). - Text in a fixed-width font like this represents a string for you to type or a BOYAN macro. Chapter 2 Getting Started with BOYAN 2.1 System Requirements BOYAN has the following minimal requirements: - IBM PC, XT, AT, or compatible with at least 256K of memory - DOS 2.0 or later - At least 600 K of free disk space (a hard disk is preferred, but not required) - An internal modem card OR a serial port and external modem - Any 80-column monochrome, CGA, EGA or VGA display BOYAN runs well under multitasking environments such as Microsoft Windows (as a non-Windows application) and Desqview. BOYAN can also make full use of a printer and mouse, although they are not required. 2.2 Setting BOYAN Up On Disk The BOYAN program and reference manual-on-disk are compressed into two "zipped" files, named BOYAN5A.ZIP and BOYAN5B.ZIP. If you receive BOYAN from a user group, ShareWare distributor, or Bulletin Board System, then it will also be in the form of the BOYAN5A.ZIP and BOYAN5B.ZIP files. BOYAN provides a DOS batch file named INSTALL.BAT which makes it easy for you to get BOYAN up and running. Install extracts the BOYAN files from the BOYAN5A.ZIP and BOYAN5B.ZIP archives and organizes them logically into subdirectories. 2.2: Getting Started with BOYAN 10 ________________________________________________________________________ Before running Install, you should have at least 600 K of free space on the disk where BOYAN will reside. (If you have only 360 K floppy disk drives, you will need two blank, formatted diskettes.) Follow these simple steps to install BOYAN: 1. At the DOS prompt, change to the disk drive containing Distribution Diskette #1. (For example, if Distri- bution Disk #1 is in disk drive A, you would type A: <Enter>.) 2. Type INSTALL C:\BOY5 <Enter> to run the batch file. It will create a new directory on your C drive named C:\BOY5. Note: to install BOYAN into a different directory, you must specify its name on the command line instead, e.g., INSTALL B: or INSTALL D:\COMM\BOYAN. The batch file will display messages on the screen to keep you informed as it is working. If for any reason you wish to interrupt the batch file before it completes, press <Ctrl-Break>. Otherwise, when installation completes successfully, you will be given the option to "Press [space] to run BOYAN". Pressing <space> will start BOYAN up, as described in section 2.3. 2.2.1 Files Included with BOYAN During installation, the following files will be extracted from the ZIP files and copied onto your drive: BOYAN.COM Main BOYAN program file BOYAN.HLP BOYAN help screens BOYAN.00* Overlay files #0 through #6 BOYAN.PIF Program Information File for Microsoft Windows B5-PIF.DVP Program Information File for DesqView BOYANNEW.DOC Summary of what's new with BOYAN 5 BOYAN.DOC The complete BOYAN user manual *.BAM Various BOYAN Action Modules VT-100.CNF Configuration file for VT-100 terminal emulation *.BSC Sample BOYAN Script files README.DOC Information about installing BOYAN README2.DOC Information about printing the BOYAN manual REGISTER.DOC A printer-ready BOYAN registration form INSTALL.BAT A DOS batch file used to install BOYAN 5 INSTALL#.BAT An auxiliary batch file used by INSTALL.BAT NEEDFREE.EXE An auxiliary utility used by INSTALL.BAT The BOYAN distribution diskettes also contain various external protocol drivers such as DSZ.ZIP (Zmodem), OZBEXT.ZIP (Compuserve-B), and PCKERMIT.ZIP (Kermit). Finally, both distribution diskettes contain 2.2.1: Getting Started with BOYAN 11 ________________________________________________________________________ PKUNZIP, Phil Katz's utility for extracting programs from the .ZIP files. Note: these programs have ShareWare licenses independent of BOYAN's; please register the ones you use with their respective authors. 2.3 Running BOYAN for the First Time 2.3.1 Running BOYAN To start BOYAN, simply type BOYAN at the DOS prompt and hit <Enter>. If you have set everything up properly, you should see the message, "Welcome to BOYAN Communications 5!" At this point, you will have to answer five basic questions: what serial port does your modem use (Com1, Com2, Com3, or Com4); what is the highest speed your modem can handle (300-38400 baud); what parity (None, Even, or Odd) should BOYAN default to; can your monitor display colors (Yes or No); and do you have a BOYAN version 5 registration code. If you are unsure about any of these questions and want to exit BOYAN, you may press <Esc> at any time. After you have answered these questions, a welcome screen will pop up while BOYAN briefly initializes. During this process, BOYAN creates the following files: BOYAN.CNF (2000 bytes) Information specific to your config- uration. BOYAN.MAC (14,700 bytes) The 120 programmable function-key macros and modem commands. BOYAN.FON (14,000 bytes) A 200-entry dialing directory. BOYAN.PWD (3000 bytes) The 200 passwords for each entry in BOYAN.FON The next time you run BOYAN, all of these files will already be present in the directory, and all initialization will occur automatically. When BOYAN's initialization is complete, the screen clears, and BOYAN initializes the modem with the "ATX4S0=0" command. The Status Line reports, "Communication ready." 2.3.2 First-time Modem Setup Before trying to establish your first connection with BOYAN, you should consult your modem manual to be sure that your modem is properly installed. If at all possible, you should set up the modem so that the "Data Terminal Ready" signal and "Carrier Detect" signal are ENABLED, rather than ALWAYS ON. The exact way to do this varies from modem to 2.3.2: Getting Started with BOYAN 12 ________________________________________________________________________ modem. Many modems, including the Hayes 2400 and the Practical Peripherals 9600SA, require the command AT&C1&D2&W <Enter>, which you may type from BOYAN's terminal mode exactly as shown. These settings will be stored even after your modem is turned off, so you only need to type this command once. On a U.S. Robotics Courier (1200,2400,or HST) modem, you must flick modem toggle switches #1 and #6 to OFF; this is the factory setting for their modems built since 1989. 2.3.3 BOYAN under Microsoft Windows BOYAN runs fine as a "non-Windows application" under Microsoft Windows 3.0. A PIF (Program Information File) for Windows is included with BOYAN. To install BOYAN into a group window in the Program Manager, do the following: 1. Select the group for BOYAN (for example, the "Non-Windows Applications" group) and make that group the current window. 2. Select "New" from the Files menu to add a new item to the group. 3. Enter drive:\path\BOYAN.PIF as the item command line, where drive:\path is your BOYAN directory (e.g., C:\BOY5). Enter anything you like for the item description and BOYAN icon. Please consult your Windows manual for details on installing new applications. 2.3.4 BOYAN under DesqView BOYAN also runs well in the DesqView multitasking environment. BOYAN is "DesqView-friendly" in that it releases unused portions of its time slice for other programs to use. The B5-PIF.DVP file provides a default configuration for running BOYAN 5 under DesqView. 2.4 The World of BOYAN Welcome! BOYAN is now in "terminal mode," ready to begin a communi- cations session. You may now type modem commands directly, or use any of BOYAN's built-in commands. There are several features common to the whole program with which you should become familiar. 2.4.1 The Status Line The bottom line of the screen is called the Status Line. The Status Line is divided into three parts--left, middle, and right. 2.4.1: Getting Started with BOYAN 13 ________________________________________________________________________ - The left part of the status line is used by BOYAN to interact with you. When BOYAN needs to display a message or get your response to a prompt, it does so here. - The middle part of the line tells you which version of BOYAN you are using. When a "script file" takes control, its name flashes here. 2 Furthermore, during terminal emulation, a small here indicates that you have selected the secondary keyset, not the primary keyset. - The right part of the line displays information about the system you dialed most recently. When you have made a connection, the line shows the name of the on-line system as well as the running elapsed time of the call. 2.4.2 <Esc> = Go Back Whenever you need to "go back" or abort your current operation with BOYAN, press the <Esc> key. This is one of BOYAN's most handy features; you can never get stuck. Remember, <Esc> to go back. If you have a mouse, pressing its right button is always the same as pressing <Esc>. 2.4.3 The Help System BOYAN's context-sensitive help screens are accessible anytime with the <F1> key. When you press <F1>, BOYAN displays the screen most likely to help you. To scan all the help screens, press <F1> while viewing a help screen. This brings up Help Page B, the Help Screen Index. Instructions there explain how to use the <PgUp> and <PgDn> keys to scroll through all 22 help pages. You can also instantly view any of the screens by pressing the letter associated with it on the Help Index. If you are in terminal mode, pressing <F1> brings up a special help screen, the BOYAN Command Menu. If you have a mouse, clicking the left mouse button also brings up the Command Menu. Any command from the list can be chosen and executed while you are viewing this help screen. In the lower-right quarter of the screen, the current on/off state of each of the "toggle" commands is shown. BOYAN commands are described fully in chapter 4. 2.4.4 Using a Mouse BOYAN 5 offers a complete interface for the Microsoft Mouse and compatibles. As you move the mouse pointer over a BOYAN menu, a scroll bar moves with it, highlighting the option underneath the pointer. Press the left button to select the highlighted option. 2.4.4: Getting Started with BOYAN 14 ________________________________________________________________________ When you are responding to a BOYAN prompt (not in a menu), you may press the left button to accept the default response. The left button is the same as the <Enter> key in this case. As mentioned above, the right button is always the same as the <Esc> key; press the right mouse button to "go back" at any time. The Dialing Directory, File Manager, Redialing Queue, and Scroll-Back Buffer offer special mouse support, including a 1-line menu at the bottom of the screen. Mouse commands specific to those areas of BOYAN are described later in this manual. If you have trouble using your mouse with BOYAN, please consult Appendix A, "Common Questions and Answers." 2.4.5 The Line Editor When using BOYAN's interactive commands, you are often asked questions. The simplest way to respond is to type in your response and press <Enter>. However, if you make a mistake while typing, BOYAN's Line Editor lets you quickly correct it. Also, BOYAN often provides a "default" value--a suggested response--for its questions. The Line Editor allows you to modify, replace, or accept BOYAN's default. The following are the Line Editor commands, which are available to you at any time as you respond to a BOYAN prompt: Accept entry as shown . . . . . . . . .<Enter> or left mouse button Move left one character . . . . . . . . . . . . . . . . <LeftArrow> Move right one character . . . . . . . . . . . . . . .<RightArrow> Move left one word . . . . . . . . . . . . . . . .<Ctrl-LeftArrow> Move right one word . . . . . . . . . . . . . . . <Ctrl-RightArrow> Go to beginning of entry . . . . . . . . . . . . . . . . . .<Home> Go to end of entry . . . . . . . . . . . . . . . . . . . . . <End> Backspace delete . . . . . . . . . . . . . . . . . . . <Backspace> Delete character under cursor . . . . . . . . . . . . . . . . <Del> Delete to end of entry . . . . . . . . . . . . . . . . .<Ctrl-End> Restore BOYAN's provided default . . . . . . . . .<Ctrl-Backspace> Toggle Insert Mode . . . . . . . . . . . . . . . . . . . . . <Ins> Insert Mode ON: flashing cursor Insert Mode OFF: block cursor These commands are also listed on Help Screen E, which you can view by keying the <F1><F1>E sequence at any time. Anxious to try an example? From terminal mode, press the <Alt-F> key to call up BOYAN's File Manager; then press (which stands for Pattern Mark). You will see the "MARK" prompt, followed by a default response of "*.*". The Line Editor cursor is over the first star. To mark all 2.4.5: Getting Started with BOYAN 15 ________________________________________________________________________ files starting with BOYAN, you would change "*.*" to "BOYAN*.*" by typing <Ins> BOYAN. Pressing <Ins> turns on Insert Mode so that the "*.*" shifts over as you type. Before pressing <Enter>, experiment a little with the Line Editor commands. When you do press <Enter>, you will see little marks next to each filename starting with "BOYAN". (If you would like to experiment with the File Manager, you may press <F1> for help, or see section 4.6.1.) Press <Esc> when you are ready to return to terminal mode. You will find the Line Editor easy and convenient after a little time with BOYAN. Chapter 3 <Alt-C> Customizing BOYAN BOYAN provides dozens of configurable options for great flexibility and power. For example, you can customize BOYAN's screen colors, disk directory usage, modem dialing commands, and many key assignments. Luckily, most of these options will be perfectly suitable at their preset (default) values. If you are just starting with BOYAN, you do not need to concern yourself with reconfiguring BOYAN's options unless you fall into one of the following categories: - You own a nonstandard modem which does not use the Hayes command set, or you wish to select "pulse" rather than "Touch-Tone" dialing. See section 3.1. - Your modem is plugged into a nonstandard serial device (a port other than Com1, Com2, IBM-PC Com3, or IBM-PC Com4). See section 3.2. - You are running BOYAN on a system with two 360K floppy drives, and no hard disk. See section 3.3. - You use a modem which allows you to lock the communications port at a high speed (4800 baud or greater) while actually connected at a lower speed. Most modems with built-in MNP error control offer this feature. See section 3.4. If you do not fit into any of those categories, BOYAN should work perfectly without your having to perform any special configuration. In that case, feel free to skip ahead to chapter 4, where you will learn how to telecommunicate with BOYAN! BOYAN's built-in configuration program makes BOYAN easy to tailor to your own needs. Call up the configuration menu by pressing <Alt-C>; a menu of configuration areas will appear. You may also use the <Alt-K> command key to go directly to Configuration Area <M> (macro and key configuration). The rest of this chapter describes each of the configuration areas in detail, beginning with section 3.5. Note: any configuration changes you make are automatically saved to disk right away. 3.1: <Alt-C> Customizing BOYAN 17 ________________________________________________________________________ 3.1 Configuring a Non-Hayes-Compatible Modem The Hayes command set is emulated by almost all popular modems. If your modem is not Hayes-compatible, however, you will have to consult your modem manual to edit the following BOYAN settings: - Modem response messages: Configuration Area <C>, options D-I. - Modem dialing command: Configuration Area <M>, subarea A, macro number 1. In particular, BOYAN's modem dialing command is preset to use Touch-Tone dialing. If your modem/phone line does not support Touch-Tone, you must configure BOYAN to use pulse dialing instead, as follows: 1. From the main <Alt-C> configuration menu, select Macros. 2. From the Macros menu, press A for Macros 1-10. 3. Type 1 <Enter> to edit the "Dialing command." 4. Use the <RightArrow> key to position the cursor over the second "T" in "ATDT"; then press P, replacing the T. The command should now read, "ATDP @SF {". Press <Enter> to accept your change. (If you make a mistake, press <Esc> instead of <Enter>, and return to step 3.) 5. Press <Esc> twice to return to the main configuration menu. 3.2 Configuring a Nonstandard Comm Device The standard IBM-PC provides for only two serial devices (ports), Com1 and Com2. However, more are often needed, and BOYAN provides support for two additional devices, named Com3 and Com4. To use those devices, BOYAN must know the exact "address" in computer memory where the device is located. BOYAN comes preconfigured with the addresses occupied by a typical Com3 device and a typical Com4 device, so if you are using one of those, BOYAN will work without additional configuration. However, if you try dialing with BOYAN and find that "nothing happens," then you need to consult the manual that came with the port to determine the proper addresses. In particular, BOYAN must be reconfigured to use Com3 or Com4 on the IBM PS/2 computers. Port addresses are configurable in BOYAN's Configuration Area <E>, options M-P. See section 3.8 for further details. 3.3: <Alt-C> Customizing BOYAN 18 ________________________________________________________________________ 3.3 Configuring a Two-Floppy System Two of BOYAN's features, the Automatic Usage Log and External Protocol file transfers, require more than the 360K of disk space available on a standard 5.25-inch floppy drive. Therefore, to use these features on a system with two 360K floppies but no hard drive, you must configure them to use the B: floppy drive, as follows: 1. From BOYAN's terminal mode (the "Communication ready" screen), press <Alt-C>, D to call up Configuration Area D: Disk & File setup. 2. Press H to edit the external protocol path, and type B: <Enter>. Now BOYAN will assume that the external protocols (on your disk labeled Protocol) will be found in the B: drive. 3. Press J to enable the usage log (option=YES). Then press K to edit the usage log filename, and type: B:BOYAN.USE <Enter>. Now the usage log will be maintained on the B: drive (the Protocol disk). 3.4 Configuring a High-Speed Modem High-speed modems are available which use automatic data-compression and error-checking to provide reliable communication at speeds exceeding 9600 bps. To get the maximum throughput from such a modem, you must configure several BOYAN options. The following discussion pertains to the US Robotics Courier HST, currently the most popular 9600 baud modem, but similar steps would work for the Hayes 9600 and other high-speed modems; please consult your modem manual for details. 1. From BOYAN's terminal mode (the "Communication ready" screen), type the following modem command, exactly as shown: AT&B1&N0&H1&W <Enter>. This instructs your USR Courier HST to communicate with the remote computer at its highest possible speed, and to communicate with your local computer at a fixed speed at all times. It also tells the modem to use CTS/RTS Flow Control to insure that BOYAN's buffers do not overflow. 2. Press <Alt-C> to call up BOYAN's configuration menu, and select C for Communications Options. Inside Configuration Area <C>, press B repeatedly until the modem speed of 19200 baud appears. Press <Esc> to return to the main configuration menu. 3.4: <Alt-C> Customizing BOYAN 19 ________________________________________________________________________ 3. Select E for Expert Communications Options. Press C to turn CTS/RTS flow control ON, and press F to change the Auto-Detect connect speed setting to NO. Press <Esc> to return to the main configuration menu. 4. Select M for Macros, and type 1 <Enter> to edit the Dialing Command macro. Then type <Ins> \CS[19200] <Enter>, changing the macro into \CS[19200] ATDT @SF { . This macro tells BOYAN to change the speed to 19200 baud immediately before dialing any number, regardless of the speed selected for that system in the dialing directory. Following those four steps will squeeze every drop of speed possible from your US Robotics Courier HST modem! For MNP-compatible modems, you may wish to use two alternate dialing commands (in BOYAN macros #1 and #2): one for normal, MNP-enabled dialing, and one for disabling MNP before dialing. For example, on MNP modems made by Intel and Practical Peripherals, you would configure the following dialing commands in Configuration Area <M>: - Macro #1: AT"\N3"\V1DT@SF{ - Macro #2: AT"\N0DT@SF{ (Other modems may use different commands.) To specify that a dialing directory entry should use the alternate dialing command (#2) instead of the normal command (#1), you simply append the letter "a" to the end of the entry's phone number. Note: processing high-speed transmissions is a very sensitive operation which may be affected by RAM-resident programs such as screen-savers or "pop-up" utilities. If you notice missing characters or other abnormalities during high-speed communication, removing the resident programs from memory may help. You might also try reducing the communication speed; even a 80386-class machine may lose characters at 38400 baud! A final option would be to invest in the National Semiconductor 16550AN UART chip, which provides automatic FIFO buffering and can significantly reduce software overhead. If you have a 16550AN, you can enable its FIFO buffering with BOYAN's macro command \BU+, as described in section 5.2.4. 3.5 Config Area <S> -- Screen, Sound, Memory Select S to see this menu. Sixteen options are listed, along with their present values. To change any option, first hit the option's letter (A-P), then enter the new value. As you edit an entry you may use the 3.5: <Alt-C> Customizing BOYAN 20 ________________________________________________________________________ BOYAN Line Editor (see section 2.4.5). You may also press <F1> for help at any time. <A> Normal text color, default = 7. This number represents the color of the text coming to and from the modem during a communications session. If you have a color monitor and wish to change this value, enter a number between 1 and 127 from the color chart at the right. Press <Enter> after typing the number. Alternatively, if you have a mouse, you may simply point at the color you want and click the left button. Enhanced text color, default = 12 (color), 15 (B&W). When BOYAN needs to highlight text on the communications screen for any reason it will use this color. <C> Menu and help screen color, default = 113 (color), 112 (B&W). BOYAN's menus and help screens will be displayed in this color. <D> Menu header color, default = 31 (color), 15 (B&W). Used for highlighting menu headers and the 1-line mouse menu. <E> Menu highlight bar color, default = 49 (color), 7 (B&W). Used for highlighting the "selected entry" in the Dialing Directory, File Manager, and Redialing Queue. Also used in mouse menus. <F> Help screen highlight color, default = 116 (color), 126 (B&W). Used for highlighting special text on the help screens as well as in some menus. <G> Status line color, default = 95 (color), 112 (B&W). <H> Scroll-back color, default = 3 (color), 7 (B&W). Text in BOYAN's scroll-back buffer will appear in this color. Macro display message color, default = 62 (color), 112 (B&W). User-generated menus, for example, will appear on the text screen in this color. <J> Beeps & Bells, default = ON. The value of this item will determine whether BOYAN's normal sound effects are on or off each time BOYAN is run. At any given time while you are using BOYAN you may temporarily toggle the sound on or off with the <Alt-B> command (section 4.1.3). This setting is independent of the alarm level. <K> Alarm level, default = 7. BOYAN uses its alarms to signal a successful redialer connection, the end of a file transfer, and a modem disconnect. Change the volume level of the alarms by setting this field between 1 (low buzzing) and 10 (loud, shrill 3.5: <Alt-C> Customizing BOYAN 21 ________________________________________________________________________ beep). 0 turns the alarm off altogether. Note that the alarm level is independent of the Beeps & Bells setting. <L> Use dots in menus, default = YES. BOYAN will enhance its menus with small dots if this option is YES. <M> Use mouse if detected, default = YES. If you have a mouse installed but don't want to use it with BOYAN, toggle this option to NO. <N> Return to Dial Dir if no connect, default = NO. If you dial a number from the dialing directory screen but the number is busy, the dialing directory will automatically reappear if this setting is YES. If this setting is NO, you will remain in terminal mode after an unsuccessful dial attempt. (Auto-dialing is explained in section 4.2.1.4.) <O> Memory (in K) reserved for DOS shell, default = 133. BOYAN uses about 170 K of memory for itself; all remaining memory is divided between the scroll-back buffer (section 4.7.2) and the DOS shell (section 4.6.2). Larger values for this option will allow you to run larger programs from within BOYAN. For example, at least 133 K is required to run "TED", PC Magazine's editor. (Other ShareWare editors such as "QEDIT" may require less.) To use the "Zmodem" external protocol, you should reserve at least 115 K. Other external protocols, like "Kermit" and "Sealink," work with as little as 65 K. Smaller values will increase the size of the scroll-back buffer. To maximize the size of the scroll-back buffer, you may set this value to 0, but then BOYAN commands like "Copy a file" will be disabled. 25 K is the smallest value that will enable DOS command use from within BOYAN. Changes to this setting do not take effect until the next time you run BOYAN. You can override the number configured here by running BOYAN with a number on its Command Line, e.g.: BOYAN 180 . Default logon password. BOYAN allows you to associate a private password with each system in your Dialing Directory. When no password is specified for a given directory entry, however, this password will be used. If you use the same password for the majority of systems you call, you may find it convenient to enter that password here rather than in each directory entry. 3.6 Config Area <D> -- Disk and File Setup Press a letter from A through P to edit these entries, all of which concern disk operations and file transfers. Remember, press <F1> for help. 3.6: <Alt-C> Customizing BOYAN 22 ________________________________________________________________________ <A> DOS command to view a file, default = TYPE. To view the contents of a text file during a communication session, BOYAN sends a command to DOS consisting of the View file command + the filename (e.g. TYPE FILENAME.EXT). If you own another file viewing utility such as Vernon Buerg's LIST program, you may use its name for this option instead. DOS command to edit a file, default = TED. When you want to edit a text file, BOYAN sends a command to DOS consisting of the Edit file command + the filename (e.g. TED FILENAME.EXT). TED is the "tiny editor" written by Tom Kihlken for PC Magazine. If your word processor is capable of editing standard text files, you may wish to enter its name here. <C> Sort filenames in file manager, default = YES. When BOYAN displays a disk directory, the filenames will be automatically alphabetized if this option is YES. If this setting is NO, the files will be displayed in the normal DIR order. <D> Default FON dialing directory, default = BOYAN.FON. Enter the name of the dialing directory which BOYAN should load at start-up. The filename should end with the .FON suffix. <E> Default path for FON directories. Enter the complete drive and directory in which BOYAN should expect to find all .FON directory files. If no path is specified here, BOYAN will assume that the files are in your BOYAN directory. <F> Default path for file uploads. When you transfer a file from your PC to a remote computer (upload), BOYAN will search this directory for the file. If it is not found in that directory, BOYAN will also automatically check the current DOS directory for the file. You may temporarily change this default path at the start of any transfer, but use this option to store your usual choice. <G> Default path for file downloads. When BOYAN transfers a file from a remote computer to your PC (download), it will automatically place the file in this drive and subdirectory. BOYAN will use the current path if this field is left empty. You may temporarily change this default path at the start of any transfer, but use this option to store your usual choice. <H> Path for external protocols. BOYAN expects to find external protocols such as DSZ.COM (Zmodem) and PCKERMIT.EXE (Kermit) in the drive and subdirectory specified here. If you are running BOYAN on a two-floppy system, you should set this path to B:. The BOYAN directory will be used if you leave this setting blank. 3.6: <Alt-C> Customizing BOYAN 23 ________________________________________________________________________ Default path for script files. When you run a script file, BOYAN searches this drive and directory for the script. If it is not found there, then BOYAN also tries to locate the script in the current DOS directory. If you leave this setting blank, BOYAN will search the BOYAN directory for the script. <J> Maintain usage log, default = YES if you are using a hard disk, NO if floppy. If you select YES, BOYAN will maintain a text file activity log which shows a record of all BOYAN connections and file transfers (see section 4.5.3). You can toggle the usage log on and off during BOYAN's operation with the <Alt-U> command. <K> Default usage log file, default = BOYAN.USE. Specify here the complete drive, directory, and filename for BOYAN's usage log file. <L> Usage log line prefix, default = %MO/%DA, %HR:%MI . This string will be appended before every line in the usage file. Any BOYAN macro variables in the string will be substituted properly. For example, with the default prefix, the Usage Message macro \UM[Disconnected!] will create a usage log entry like "05/28, 11:35 Disconnected!". <M> Default log to disk file, default = BOYAN.LOG. BOYAN can auto- matically save all incoming text to a disk file (section 4.5.1). Although you can change this name each time you log to disk, the default directory and filename should be set here. <N> Default screen dump file, default = SCRNDUMP.TXT. BOYAN's <Alt-S> command saves a copy of the current screen to a disk file (section 4.5.2). Use this option to specify the directory and filename BOYAN should use for this file. <O> Scroll-back filename, default = SCRBACK.LOG. When viewing text in the scroll-back buffer, you may mark any region of text to be saved to a disk file (section 4.7.2). Specify this file's default directory and filename here. Default phone list dump file, default = NUMBERS.TXT. BOYAN can generate a readable text file listing of the phone directory (section 4.2.1.4). Specify this file's default directory and filename here. 3.7: <Alt-C> Customizing BOYAN 24 ________________________________________________________________________ 3.7 Config Area <C> -- Communications options Select a letter from A through P to change any of these entries. The defaults for these settings apply to a typical computer with a Hayes- compatible modem. <A> Serial device (port) to use. Toggle this option to Com1, Com2, Com3, or Com4 to specify the serial port which BOYAN should use when it starts up. This can be changed temporarily during terminal mode with the <Alt-P> Parameter Change command (section 4.2.3). Note: if you are using the Com3 or Com4 port, you may need to specify the port addresses in Configuration Area <E> (see section 3.8). Modem speed. BOYAN will automatically use the baud rate you select here (300, 1200, 2400, 4800, 9600, 19200, or 38400) when it starts up, but this rate can be changed at any time with the <Alt-P> command (section 4.2.3). <C> Parity setting. BOYAN will automatically use the parity you select (None, Even, Odd) when it starts up, but this can be changed at any time with the <Alt-P> command (section 4.2.3). Most Bulletin Board Systems will work with a setting of None, whereas most mainframes, databases, and large services such as CompuServe require a setting of Even. BOYAN automatically selects a "word length" of 8 bits for No parity, and 7 bits for Even or Odd parity. <D> Modem connect message, default = CONNECT. If your modem gives a message upon making a connection, enter that message here. Note that "CONNECT" will cover the extended messages of "CONNECT 1200", "CONNECT 2400", etc. <E>,<F>,<G>,<H> Modem no connect messages, defaults = BUSY, NO CARRIER, NO DIAL, and VOICE. When your modem sends any of the four messages entered here, BOYAN will assume that the attempted dialing was unsuccessful. If your modem has fewer than four such messages, just leave the extra spaces blank. Modem error message, default = ERROR. If BOYAN sees this message it will know that an error in dialing occurred, and it will not attempt to redial this number. <J> Echo keyboard, default = OFF. If off, BOYAN will send what you type to the modem only; if on, BOYAN will send what you type to both the modem and the screen. This may be toggled temporarily during communications with the <Alt-E> command (section 4.1.4). 3.7: <Alt-C> Customizing BOYAN 25 ________________________________________________________________________ <K> Add linefeeds, default = OFF. BOYAN will add linefeeds (extra line spacing) to incoming carriage returns if this option is on. While using BOYAN you may temporarily toggle linefeeds on or off with the <Shift-Tab> command (section 4.1.10). <L> Default file transfer protocol, default = X. This is the default protocol BOYAN will offer when the "Prot" field in the dialing directory entry has been left blank. BOYAN version 5 supports the following methods of file transfer: [X]modem, [C]RC-Xmodem, [R]elaxed-Xmodem, [1]K-Xmodem, [Y]modem, [G]-Ymodem, and [A]SCII. These protocols are described in section 4.4.1. BOYAN also supports up to ten user-defined external protocols, such as [Z]modem and [K]ermit. Note that you can still use any protocol at any time, no matter what the default. <M> Check free disk space before DL, default = YES. When this is YES, BOYAN will automatically display the number of bytes available on the drive before downloading a file and while viewing the Directory File Manager. When this is NO, you must press <Alt-F> in the download menu or Y in the Directory File Manager to accomplish the same result. If you have a relatively slow hard disk with a large amount of free space on it, you can save some time by setting this option to NO. <N> Auto-find transfer filename, default = YES. With most communications programs, transferring a file requires you to enter the file's name twice: once to the remote computer, and once to your PC. One of BOYAN's most handy features is its ability to "lift" a filename right off the screen, saving you the trouble of typing it twice (section 4.4.3). Select OFF to disable this feature. <O> Auto-detect message upload word wrap, default = NO. BOYAN's message upload feature allows you to prepare messages offline with your word processor and then send them directly to the remote message system. Since different systems allow different maximum lengths for each line of the message, uploaded message sometimes look strangely short on the line, or (worse yet) they overrun the line, causing word wrap. When this feature is ON, BOYAN will automatically detect when the remote system word wraps; if this happens, BOYAN suppresses the next <Return> character. This works nicely with text messages, but may cause graphic boxes and the like to align improperly if the message line is too long. Note that this feature is disabled by default. Auto-downloading, default = ON. Downloading with certain protocols, such as Zmodem, MPt, and Bimodem, will start without your having to touch the keyboard if this option is ON. See section 3.12.1 for a full discussion of auto-downloading. 3.8: <Alt-C> Customizing BOYAN 26 ________________________________________________________________________ 3.8 Config Area <E> -- Expert Communications Options Select the option to configure by letter (A-P). <A> Inter-character pacing (ms), default = 10. How many thousandths of a second to delay between sending characters in a macro, ASCII upload, or Message upload. Line pacing (ms), default = 20. An additional delay, in thousandths of a second, after sending a Carriage Return in a macro, ASCII upload, or Message upload. <C> Use CTS/RTS flow control, default = NO. Some high-speed modems support so-called "hardware handshaking," or CTS/RTS flow control, in order to prevent buffer overflows. If your modem can be set to use CTS/RTS handshaking, you should set this option to YES. <D> Use XON/XOFF flow control, default = NO. Some high-speed modems and networks support "software handshaking," or XON/XOFF flow control, in order to prevent buffer overflows. BOYAN will recognize and use XON/XOFF controls if this option is set to YES. Note: CTS/RTS flow control is preferable and should be used instead of this option, if your modem supports it. <E> Drop DTR when closing communications port, default = YES. When you exit BOYAN or change comm devices, BOYAN will drop the Data Terminal Ready signal if this option is set to YES. If you wish to exit BOYAN without losing your data connection, toggle this option to NO. <F> Auto-detect connect speed, default = YES. When this is YES, BOYAN will automatically set its baud rate based on the number returned with the modem connect message after dialing. In effect, using this option allows you to specify your highest modem speed for every dialing directory entry, as long as your modem returns a message with its connect speed. If your modem only reports "CONNECT" and not a baud rate like "CONNECT 1200", then you should set this option to NO. You should also set this option to NO if you are using a high-speed modem with a fixed port speed. <G> Modem carrier detect mask bit, default = 7. Many of BOYAN's features depend on your modem's ability to accurately reflect its carrier status. Most modems use bit 7 of the modem status register to indicate the presence of a carrier signal. For some modems, you may have to type a special command or flick a modem dipswitch to get it to accurately reflect the carrier status (see section 2.3.2). If BOYAN seems to think you are connected when 3.8: <Alt-C> Customizing BOYAN 27 ________________________________________________________________________ you aren't, or vice-versa, then as a last resort try changing this number to 5, 4, etc. <H> CD reflects true state of modem, default = YES. If your modem can accurately maintain the Carrier Detect signal as described in section 2.3.2, then this option should be YES. When you try to dial a number while your modem is already reporting a carrier signal, BOYAN will ask you to confirm that you really want to "dial despite carrier." If your modem always forces the carrier signal high, you will want to eliminate this prompt by setting this option to NO. Time to wait for connect, default = 45. After dialing a number, BOYAN waits this many seconds for a carrier signal, a modem message, or a keypress. If the timer expires, BOYAN assumes that no connection was made. Note: many modems have their own timer and will report "NO CARRIER" after 30 seconds. Check your modem manual if you want to modify the modem's internal timer. <J> Time between redials, default = 3. After an unsuccessful dialing attempt from the queue redialer, BOYAN pauses for this many seconds before running the "Cycle current dialing" Auto-macro and then continuing to redial. <K> Script "waitfor" timeout, default = 40. BOYAN's macro/script waitfor commands will wait for the number of seconds specified here before "timing out" and continuing to the next command. If you enter the maximum value, 255, then BOYAN will wait indefinitely for a match. This value can be reset from within a macro or script by the \TO macro. <L> Script keyboard timeout, default = 10. When a script file has control, BOYAN thinks of itself as "unattended" and will accept the default response to any keyboard prompt--but only after pausing for this many seconds. During that pause, if you are at the keyboard, you may edit the default response using the BOYAN Line Editor. This setting also controls how long BOYAN will ring the redialing queue connect alarm before proceeding to run the associated auto-logon script. This value can be reset from within a macro or script by the \KO macro. <M> Com3 port address (hexadecimal), default = $3E8. Com3 is not a standard IBM serial device, so different add-in devices may use different "addresses" in memory for the communications port. On the IBM-PC and AT, $3E8 is most often used; on the IBM PS/2, Com3 is addressed at $3220. You will get unpredictable results if you try to use Com3 when this value is not set properly. Addresses should be entered in hexadecimal notation, with or without a "$" prefix. 3.8: <Alt-C> Customizing BOYAN 28 ________________________________________________________________________ <N> Com3 interrupt (IRQ 2..5), default = 4. Serial ports can use IRQ 2, 3, 4 or 5 for their "interrupt requests." Your Com3 device's documentation should specify which it uses. <O> Com4 port address (hexadecimal), default = $2E8. See the description of configuration option <M> above. On the IBM PS/2, Com4 is addressed at $3228. Attempting to use Com4 if this value is set incorrectly will cause unpredictable results. Addresses should be entered in hexadecimal notation, with or without a "$" prefix. Com4 interrupt (IRQ 2..5), default = 3. Your Com4 device's documentation should specify which IRQ line it uses. 3.9 Config Area <M> -- Macros A BOYAN "macro" is a line of text, up to 80 characters long, which contains a sequence of instructions for BOYAN to follow. BOYAN recognizes well over 300 different two-letter macro commands. By learning BOYAN's Macro Programming Language, you can customize almost every aspect of BOYAN's operation. The Macro Programming Language is described in detail in chapter 5. 3.9.1 Basic Macro Commands Short of mastering the Macro Programming Language, you can still use macros in their most basic form. The simplest macro is just a string of text, such as John Doe. When that macro is executed, BOYAN sends the string John Doe over the modem, just as if you had typed the name manually. If you assigned the macro John Doe to a function key (say <F2>), then at any later time you would only need to press <F2>, and the string John Doe would be typed out. The eight characters " ^ { ~ ` \ % @ have special meanings in a BOYAN macro. When any of those characters are used in a macro, they are not sent directly to the modem, but instead have the following effects: 1. The quotation mark " is used before any of those eight characters if you really do wish that character to be sent directly to the modem. For example, to send a quotation mark, include "" in your macro. To send a backslash, use "\. 2. The caret ^ is used to send control characters. For example, if the string ^J is found in a macro, BOYAN will send a control-J character. ^[ sends an Escape character. 3.9.1: <Alt-C> Customizing BOYAN 29 ________________________________________________________________________ 3. The left curly brace { is used to send the <Return> character. It is equivalent to the macro command ^M , or typing <Enter> from terminal mode. 4. If the tilde ~ is found in a macro, BOYAN will pause one-half second before continuing. 5. The backquote ` is ignored unless preceded by a quotation mark. It may be used for spacing out BOYAN commands. 6. The backslash \ is the BOYAN Macro Programming Language command prefix. BOYAN's macro commands generally take the form of a backslash followed by two letters. These commands, described in chapter 5, make it possible for you to automate all your communication needs. 7. The percent sign % and at-symbol @ are the BOYAN Macro Programming Language variable prefixes. BOYAN macro variables take the form of either a percent sign or at-symbol followed by two letters. Chapter 5 also covers these variables. Spaces in a macro are ignored when they fall between two macro commands or at the end of the macro. However, they are sent literally to the modem when found in the middle of a string, such as in Jane Doe. A macro to send only a single space would be a quotation mark " followed by a space. Two backslashes in a row \\ signify a macro comment; BOYAN ignores any text following those two characters. Many of the 120 built-in BOYAN macros end with comments which help explain their functions. 3.9.2 The 120 BOYAN Macros In Configuration Area <M>, there are 120 macros available for config- uration. Here is a summary of how all 120 macros are arranged: - 1-5: Dialing commands; Reset modem parameters; Hang up modem; Cycle current dialing. These are explained in the next section. - 6-14: BOYAN Auto-macros. The nine Auto-macros help make BOYAN uniquely powerful among communications programs. These macros automatically "come to life" at specific times during normal BOYAN operations. They are also explained in the next section. - 15-110: Keystroke macros. Every function key and BOYAN command key is assigned its own macro, which you can examine and customize to your liking. This is demonstrated below in section 3.9.4. 3.9.2: <Alt-C> Customizing BOYAN 30 ________________________________________________________________________ - 111-120: Shortcut macros. These correspond to the symbols above the top row of digits on the keyboard -- the ! @ # $ % ^ & * ( ) symbols. They are shortcuts because they may be invoked within any other macro, by using the macro command \ plus the symbol. In other words, if you assign macro 113 (#) to the string John Doe, then you can embed the \# string within any other macro to send "John Doe". If you assign macro 117 (&) to print the disk directory and download a file, then including \& within any macro or script will do the same thing. A common use for shortcut macros is long-distance dialing prefixes. This is explained in section 4.2.1.5. From the Macro menu, you may select a group of 10 macros to view by choosing the appropriate letter from the menu (A-L). Alternatively, you may go directly into editing a particular macro, by typing its number and pressing <Enter>, or in the case of a keystroke or Shortcut macro, just hitting the appropriate keystroke. You may use the BOYAN Line Editor commands while editing a macro (see section 2.4.5). While viewing a screen of BOYAN macros, you may use the <PgUp> and <PgDn> keys to move from screen to screen. 3.9.3 Modem Dialing & Auto-macros BOYAN Macros 1-14 perform basic modem commands and other functions important to BOYAN's routine performance. Press A to go from the Macro menu to a list of BOYAN macros 1-10, or B to list macros 11-20. To edit any of these, type its number and press <Enter>. Do not worry if some of the Auto-macros appear very complex; you can use BOYAN fully without changing any of them! For examples of how to customize the Auto-macros, please refer to section 5.3.2. 1. Dialing command, default = ATDT @SF {. When you tell BOYAN to dial a number from your Dialing Directory, it does so with this macro, substituting the system's phone number for @SF. 2. Alternate dialing command. You may enter another dialing command here, using the same format as macro #1. A system in your Dialing Directory will be dialed using this alternate macro if you append the letter "a" to its phone number. 3. Reset modem parameters, default = \CA-[{~]. BOYAN automatically runs this macro after you change the modem's baud rate or parity settings with the <Alt-P> command. The default uses BOYAN's \CA- macro command to act as follows: if there is no carrier (you are not on-line at the time when you press <Alt-P>), then it sends a Carriage Return to the modem and pauses for one-half second. 4. Hang up modem, default = \DT- \RE5[\CA+[~]] \DT+ \CA+[+++~~~~ATH{]. When you press <Alt-H> to hang up the modem, BOYAN invokes this macro. The default macro drops the Data 3.9.3: <Alt-C> Customizing BOYAN 31 ________________________________________________________________________ Terminal Ready signal (\DT-), then pauses until either the carrier signal drops or 2.5 seconds have elapsed. After restoring the DTR signal (\DT+), if BOYAN still detects a carrier signal, then it sends the normal Hayes-compatible hangup command: +++ , pause, ATH <Enter>. 5. Cycle current dialing, default = { . Often a modem will take 15 or 20 seconds to determine that the number it has dialed is busy. If you have a modem speaker, BOYAN lets you manually cycle (cancel) the dialing attempt as soon as you hear the busy signal. This macro is sent at that time. The default macro sends the <Return> character, which cycles most Hayes-compatible modems. On Everfax modems, this macro should be changed to A/. 6. After connecting, default = \UM[%SN (%MS baud): %SF]. This Auto- macro runs immediately after you connect to any system. The default simply adds a Usage Message to the BOYAN.USE file with the system name, modem speed, and system phone number. 7. After disconnecting, default = \AL3[0] \RC \SK- \UM[| Disconnected after %SL]. This Auto-macro runs immediately after you disconnect from any system. The default sounds a brief alarm, resets the text color, turns off the Secondary Keyset, and adds a "Disconnected" message to the BOYAN.USE usage file. 8. After a file transfer, default = \AL1[1] \UM[| %TI]. BOYAN runs this Auto-macro after any file transfer. The default rings alarm #1 for one second, and then adds a message to the usage log with a line of file transfer information (%TI). 9. BOYAN start-up macro, default = \DM[ Welcome to BOYAN Communications 5! ] \CA-[ATX4S0=0{] . This Auto-macro runs right after you enter BOYAN. By default, Macro #9 first displays a welcome message, and then initializes the modem with the ATX4S0=0 <Return> command only if there is no carrier signal detected. This initialization string tells most Hayes-compatible modems to give extended dialing result codes and to not answer the phone when it rings. If your modem requires a different initialization string, it should be inserted in this macro inside the \CA-[..] command. 10. BOYAN conclude macro, default = \LD-. This Auto-macro runs right after you tell BOYAN you want to exit the program. The default closes any open log file before exiting. 11. Mouse click macro, default = \HE. Here you can specify exactly what BOYAN will do if you click the left mouse button while in terminal mode. By default this brings up the Command Menu. 3.9.3: <Alt-C> Customizing BOYAN 32 ________________________________________________________________________ 12. Auto-download, default = \AT+[\DL-[]]. When the remote system sends a message to begin auto-downloading with a certain protocol, BOYAN makes that protocol the default protocol and then runs this Auto-macro. The default macro checks that no script is running (\AT+[..]) before starting the download immediately. If you prefer to confirm the auto-download before it starts, simply remove the minus sign from the \DL command. Please see section 3.12.1 for a full discussion of auto-downloading. 13. Printer init macro, default = \PM[==== BOYAN Printer Log, %MO/%DA/%YR at %HR:%MI ===={]. When you select the Initialize option from BOYAN's Printer Menu, this Auto-macro runs. The default prints a header message with the date and time. You may add control codes to the macro, e.g., \PM[^XB] to send <control- X>, to the printer. 14. Log file init macro, default = \LM[==== BOYAN Log to Disk, %MO/%DA/%YR at %HR:%MI ====]. This Auto-macro runs immediately after you open a log file. The default macro logs a header message with the current date and time. 3.9.4 <Alt-K> Function Key Customization Each cursor key, <Alt-letter> or <Alt-number> keystroke, and function key is assigned to a BOYAN macro, numbers 15 through 110. By editing those macros, each can be customized to perform any BOYAN action you want. For example, suppose you wanted to customize BOYAN so that pressing the <F9> function key would have the effect of typing your name, pressing <Enter>, pausing, then typing your password and pressing <Enter> again. It's as easy as 1-2-3: 1. Call up BOYAN's Configure Macro menu by pressing <Alt-K>. Then select the <F9> keystroke macro for editing by simply pressing <F9>. 2. Type in the macro: John Doe{~%PW{ . The { symbol causes the macro to send a Carriage Return. The tilde ~ inserts a half- second pause. Finally, %PW is a Macro Variable which always contains the current system's password. But before you press <Enter> to save your macro... 3. Press <UpArrow> to enter a description of your macro, e.g. Type name & password. Then press <Enter>. BOYAN automatically saves your new macro to disk. To escape back to BOYAN's terminal mode, press <Esc> twice. Now, if you press <Alt-F1>, you will notice that the function key menu lists "F9: Type name & password" as an option. The next time you are online, pressing <F9> will send your name and password automatically! 3.9.4: <Alt-C> Customizing BOYAN 33 ________________________________________________________________________ A function key macro can do more than just send text: it can run another program, enter a new terminal emulation, download a file, change disk directories, select a new modem speed, or automate an entire communications session. Furthermore, by editing the pre-programmed BOYAN command macros, you can customize BOYAN's keyboard layout entirely to your own taste. Chapter 5 covers BOYAN's Macro Programming Language. 3.10 Config Area <A> -- BOYAN Action Modules BOYAN Action Modules (BAMs) are stored in the BOYAN directory as files with the ".BAM" suffix. The Action Modules included with BOYAN 5 are ADM-3A, ANSI-BBS, CONTROL, DOORWAY, DUMBTERM, GOSSIP, HOST, IBM-3101, TVI-925, VT-52, and VT-100. These are described in section 4.3. When additional Action Modules are written for BOYAN 5, the .BAM files will be available for download from the BOYAN Support BBS, and they may be easily integrated into BOYAN 5. Configuration Area <A> has two functions: to maintain BOYAN's list of available Action Modules; and to perform special configuration for each individual module. 3.10.1 BAM Selection The top four items on the configuration screen are the same no matter what BAM is currently active: <A> Add action module to list. When new BAM files become available for use with BOYAN, you tell BOYAN 5 to recognize them by adding their name to the list. You must choose a single letter or digit to represent the new action module in menus. Remove action module from list. If there are .BAM files which you never use, you may save a bit of time and disk space by deleting those files from the disk and then removing their names from this list. <C> Change current action module. This option allows you to select the current action module, just as if you were choosing from the <Alt-A> menu. The lower half of the screen will reflect the special configuration options for the newly-selected BAM. <D> Change default action module (default = ANSI-BBS). BOYAN will use the BAM you select here automatically at start-up. For example, if you want BOYAN to be in Gossip Mode at start-up, touch G after selecting option D. Note: the DOORWAY and HOST modules may not be used as the default BAM. 3.10.2: <Alt-C> Customizing BOYAN 34 ________________________________________________________________________ 3.10.2 Terminal Emulation Configuration The lower half of the screen in Config Area <A> shows special options available for the currently-selected BAM. If you use option C to select another BAM, a new set of special options will appear there. Each terminal emulation BAM (ADM-3A, ANSI-BBS, IBM-3101, TVI-925, VT-52, and VT-100) offers a selection of options from the list below: - Edit secondary keyset. The secondary keyset changes the meanings of the function and cursor keys while <Scroll Lock> is locked. Pressing E brings up a menu in which all of the special keyboard functions can be customized to the particular BAM. Configuring these keys works in exactly the same way as configuring BOYAN's primary keyset, as described above in section 3.9.4. For a complete description of how to redefine the terminal emulation keysets, please refer to Appendix D. Press <Esc> to return to Config Area <A>. - Swap Backspace/Del keys, default = NO. When this option is NO, pressing <backspace> sends the standard BS character (ASCII 8), while pressing <Del> sends the DEL character, ASCII 127. If you set this option to YES, the two keys will be switched, so that <backspace> sends DEL and <Del> sends BS. This is useful on mainframes which require the DEL character to delete backwards. - Wrap long lines, default = YES. Lines of text with more than 80 characters on them are wrapped to the next line if this option is YES, or truncated at the 80th column if this option is NO. - Backspace at column 1, default = NO. (TVI-925 emulation only) When this is ON, a backspace received when the cursor is on column 1 will cause the cursor to "back up" to column 80 of the previous line. When OFF, such a backspace has no effect. 3.10.3 Host Mode Configuration The BOYAN Host Mode uses both the HOST.BSC script file and the HOST Action Module. The Action Module provides five configurable options: <E> Edit host user database. Up to 70 host users may be entered in this sub-menu. Each entry should have the form Firstname Lastname;password;# where # is that person's user level (0,1, or 2). After the user level, you may also add another semicolon followed by any text. The following is an example entry in the Host user database: Justin Boyan;ibm-pc;2; hasn't called since August 3.10.3: <Alt-C> Customizing BOYAN 35 ________________________________________________________________________ The HOST script automatically adds new users to this database and assigns them a user level of 0. Technical note: for purposes of the \TV and \TM macro commands, the host user database is considered a "secondary keyset," where each user entry corresponds to a keyset macro numbered 41 through 110. <F> Host message directory, default = HOST. The host will use this directory for storing user-written public messages as well as the file of private comments to the operator. <G> Host files directory, default = HOST\FILES. The host will use this directory for file transfers. This should not be the same as the BOYAN home directory, so that level 1 callers will not download the host database file with the passwords in it! <H> Number of phone rings, default = 1. The host will answer the phone after seeing this many "RING" messages from the modem. Connection is by modem, default = YES. If you are establishing a direct link between two computers, and wish the host to bypass its normal procedure of waiting for the phone to ring, then change this option to NO. <J> Local test mode, default = OFF. When local test mode is ON, all text which is normally sent over the modem is displayed on your screen instead. In this way, you can test the host mode from the keyboard exactly as if you were operating it remotely. 3.11 Config Area <T> -- Translation/filter table The ASCII character translation and filter table is used if you want BOYAN automatically to change or remove incoming characters. Directions for using the translation table are on the screen. Pressing <F1> gives you instant access to an ASCII reference chart, which assigns a number between 0 and 255 to each letter and symbol. Example 1: If the square-root symbol (char #251) appears erratically on your screen during a bad line connection, you could have BOYAN simply filter it out. Type F 251 <Enter>. Example 2: You want the ASCII "DEL" character (#127) to be interpreted as a backspace (#8) when it is received. Type T 127 <Enter> 8 <Enter>. Example 3: After connecting to a mainframe, your screen fills up with graphics symbols and foreign letters. One way to correct this problem is to use a modem parity setting of Even instead of None (this can be changed in the dialing directory). Another solution is to select "Strip 3.11: <Alt-C> Customizing BOYAN 36 ________________________________________________________________________ 8th bit" in the translate/filter table. This option converts all ASCII characters with codes greater than 128 to regular non-graphics ASCII characters. The "D" option from the translate/filter table allows you to tell BOYAN whether or not to obey the translate table by default, that is, whether the translate table should be on or off when BOYAN starts. During a communication session you may turn the translation table on or off at any time by pressing <Alt-T>. 3.12 Config Area <X> -- External File Transfer Protocols BOYAN provides built-in support for the Xmodem, Relaxed-Xmodem, CRC- Xmodem, 1K-Xmodem, ASCII, Ymodem, and G-Ymodem methods of file transmission. However, BOYAN can also support up to ten additional protocols by calling external programs. BOYAN comes preconfigured to support Kermit (via PCKERMIT), Zmodem and Ymodem-batch (via DSZ), Compuserve Quick-B (via OZBEXT), Sealink, Megalink, MPt, and Bimodem. (Please note: these external protocols are copyrighted software, with ShareWare license agreements independent of that of BOYAN Communi- cations.) Furthermore, any additional protocol may be configured into BOYAN. BOYAN's procedure for using external protocols is as follows: 1. Check that the external program exists in the External Protocol directory (specified in Config Area <D>). 2. Set the current DOS drive and directory to be the upload or download directory. 3. Execute a user-defined macro which shells to the external program with all necessary parameters. 4. When the transfer is complete, change back to the previous default drive and directory, and return to the "Communication ready" screen. BOYAN needs to know seven pieces of information about each external protocol you wish to configure. To help explain, suppose you want to add the fictitious "Vmodem" protocol, which is supported by an external program named VMODEM.EXE. Vmodem transfers are initiated by the following DOS commands: Upload: VMODEM -speed #### -send FILENAME.EXT Download: VMODEM -speed #### -receive FILENAME.EXT 3.12: <Alt-C> Customizing BOYAN 37 ________________________________________________________________________ Here is how you would fill in the information BOYAN needs: - A protocol name of up to twelve letters: Vmodem. This is how the protocol will be identified in the protocol menu and in the usage log. - A menu selection letter (or digit): V. This letter will be used to select the protocol from the protocol menus and in macro commands. If you choose X, R, C, 1, Y, G, A, or M, then the internal BOYAN protocol corresponding to that letter will be overridden. - The name of the external file which is responsible for handling the transfer: VMODEM.EXE. BOYAN makes sure that this file is present (in the external protocol directory) before allowing you to select this protocol. - Batch protocol: NO. Protocols more sophisticated than our hypothetical Vmodem receive download filename(s) from the sending program, in which case this option can be set to YES. Note, however, that you must select NO if you want BOYAN to record file transfer information in the usage log; when YES is selected, BOYAN has no way of knowing what file(s) have been downloaded. - Auto-download string: can be left blank. (See section 3.12.1 below.) - Upload macro: \DC-[%P:VMODEM -speed %MS -send %TF]. Most external file-transfer programs require parameters after the filename to tell them the modem device (port 1, 2, 3, or 4), the modem speed, and the name of the file to transfer. Use the format \DC-[%P:progname .. ] for each upload macro. Handy Macro Variables for an upload macro include: %P: the name of the external protocol directory %TF The transfer filename %MD Modem Device number (1, 2, 3, or 4) %MS Modem Speed (300, 1200, ..., 38400) %MP Modem Parity (N, E, or O) %MA Modem port address in hexadecimal %MN Modem interrupt IRQ line (2, 3, 4, or 5) - Download macro: \DC-[%P:VMODEM -speed %MS -receive %TF]. 3.12.1: <Alt-C> Customizing BOYAN 38 ________________________________________________________________________ Refer to the predefined macros and to the help screen for further information. Although protocol configuration can be complex, it is yet another of the features that makes BOYAN uniquely flexible. 3.12.1 Auto-downloading Suppose you have reached a BBS and have told it that you want to download a file using Zmodem. It usually gives you a message such as "Sending FOO.ZIP--start the download on your end now." Then it starts the actual Zmodem file transfer, which always begins with the four characters <Ctrl-X>,B,0,0. Those particular four characters rarely occur in a sequence together except at the start of a Zmodem transfer. What BOYAN can do is to always "keep a lookout" for that four-character sequence. When it sees it, it starts the Zmodem download right away--without your having to lift a finger. This is the essence of auto-downloading. In fact, BOYAN can keep a lookout for up to ten different auto-download sequences, one for each external protocol specified in Configuration Area <X>. Each sequence may contain a maximum of seven characters. Control characters should be entered as a caret ^ plus the letter; to specify a caret itself as part of the sequence, enter "^. If the desired auto-download sequence is more than seven characters long, just choose any seven-character subsequence: the important criterion is that the sequence be unlikely to occur except when starting a download. What actually happens when BOYAN recognizes one of the ten auto-download sequences is this: it sets the default protocol (%DP) to the letter of the protocol detected, and then executes BOYAN Auto-macro #12 (described in section 3.9.3). Auto-downloading may be disabled by toggling option P in Config Area <C>, or with BOYAN Macro Command \AU-. Chapter 4 BOYAN Command Capabilities When BOYAN is in terminal mode, it lets you communicate through the modem without obstruction. However, at all times BOYAN's many commands are one keystroke away. This chapter describes in detail how to use the BOYAN commands. 4.1 Basic Commands 4.1.1 <F1> Help Menu While in terminal mode, pressing <F1> brings up a menu of available BOYAN commands. The menu is split into five categories: Modem, Action Module, Utility, Dos & File, and Toggles. Note that the current ON/OFF status for each of the toggles is displayed. To execute a command, type the keystroke to the right of the command's description. To view the help screen index and gain access to all of BOYAN's help screens, press <F1> again (see section 2.4.3). If you prefer to return to terminal mode without executing a command, simply press <Esc>. Mouse users: on this menu and all others, you may make a selection by pointing to a command and clicking the left mouse button. 4.1.2 <Alt-F1> Function Key Menu Pressing <Alt-F1> brings up a menu of 40 function keys. You may select commands from this menu just as from the <F1> main help menu. What is special about this menu is that each of the 40 descriptions is user-definable. To change the description of a function key, press <Alt-K>, the function key itself, and then <UpArrow>. Refer to section 5.3 for many examples of user-defined keys. 4.1.3: BOYAN Command Capabilities 40 ________________________________________________________________________ 4.1.3 <Alt-B> Beeps & Bells Toggle The Beeps and Bells setting is a toggle, taking the value ON or OFF. When BOYAN starts, it will set this toggle to its configured default (section 3.5). Note that the alarms will still sound even if the Beeps and Bells toggle is OFF. To silence BOYAN completely, you must configure the Alarm Volume to 0, as well as turn Beeps and Bells OFF. 4.1.4 <Alt-E> Echo Keyboard Toggle When the Echo Keyboard Toggle is switched OFF, every character you type is sent to the modem only. When this toggle is ON, each character is sent to both the modem and the local screen. If you see double of everything you type, or if you can't see what you type at all, try pressing <Alt-E>. You may set BOYAN's initial value for this toggle in section 3.7. 4.1.5 <Alt-G> 43/50-Line Mode Normally, when this toggle is OFF, BOYAN displays 25 lines of text on the screen whether your adapter is a Monochrome, CGA, EGA, or VGA. However, if you have an EGA or VGA adapter, you may "grab" more screen lines by pressing <Alt-G>. An EGA screen will then display 43 lines; a VGA, 50 lines. Note that BOYAN menus and help screens will still only use the top 25 lines, except for the Scroll-back buffer, which utilizes the whole screen. Press <Alt-G> again to return to a 25-line screen. 4.1.6 <Alt-O> Restore Default Text Color If a system sends an ANSI Graphics or other terminal emulation code that changes the text color, you can change it back to its configured default by pressing <Alt-O>. 4.1.7 <Alt-T> Translation Table Toggle When this toggle is selected ON, BOYAN will translate or filter incoming ASCII characters as specified in the translation table (section 3.11). When OFF, all characters are displayed without modification. 4.1.8 <Alt-X> Exit BOYAN When you have finished a BOYAN session and wish to quit, press <Alt-X>. Press Y to verify the exit, or N to stay in BOYAN. If you exit while still connected through the modem, you will be given a message to that effect. The modem port will be closed, and the DTR signal will be held or dropped depending on your configuration (see section 3.8). 4.1.9: BOYAN Command Capabilities 41 ________________________________________________________________________ Be careful not to confuse this command with the <Alt-J> Jump to Dos command (section 4.6.2), which lets you enter DOS temporarily but keeps BOYAN in memory. 4.1.9 <Alt-Z> Zap (Clear) Screen To clear the current screen of text, press <Alt-Z>. The status line will remain intact. 4.1.10 <Shift-Tab> Add Linefeeds Toggle When this option is ON, BOYAN adds linefeeds to all incoming carriage returns; when OFF, all carriage returns are processed as is. If all text is double spaced, or if all text is overprinted on the same line, try pressing <Shift-Tab>. You may set BOYAN's initial value for this toggle in section 3.7. 4.2 Modem Commands 4.2.1 <Alt-D> Dial a System BOYAN makes it simple to make connections through an auto-dialing modem, either with a phone number entered manually or a number from one of its 200-entry dialing directories. Before using the <Alt-D> command to dial, be sure that your modem's dialing commands are properly configured (section 3.9.3). When you press <Alt-D>, the dialing directory appears, and you are prompted to "Enter a phone number or a command." You may now either 1) enter a full phone number to dial manually; 2) enter a code number between 1 and 200 to dial a system from the directory; or 3) press any of BOYAN's dialing option keys. 4.2.1.1 Manual Dialing Automatic dialing from the BOYAN directory has many advantages over manual dialing: BOYAN automatically sets the parameters, maintains information about the system, and lets you abbreviate with a short dialing code number. Nevertheless, manual dialing is sometimes convenient if you wish to just try a system once without permanently changing your directory. To dial manually, first use the <Alt-P> command to set the modem's parameters to the proper values. Then dial by typing <Alt-D>, the system's full number, and <Enter>. What happens next is explained below in section 4.2.1.3. 4.2.1.2: BOYAN Command Capabilities 42 ________________________________________________________________________ 4.2.1.2 Code Number Dialing To dial a system which has already been entered into the Dialing Directory, select the entry either by using the cursor keys or by simply typing its code number (1-200); then press <Enter>. If the system's baud rate and parity are different from the current settings, BOYAN automatically adjusts the settings and runs the Reset Modem Parameters macro (#3). Then BOYAN dials the number. 4.2.1.3 After Dialing After BOYAN has dialed a number in either of the two ways described above, it waits for 45 seconds (to change this, see section 3.8) for the modem to return a message. BOYAN chooses one of several paths depending on what happens in those 45 seconds: 1. If you press the <Esc> key, BOYAN's dialing procedure is aborted, and control is immediately returned to you in terminal mode. The modem may still be trying to establish a connection. 2. If the modem returns an error message, BOYAN cycles (cancels) the current dialing attempt with the Cycle Dialing Auto-macro (section 3.9.3) and returns you to terminal mode. 3. If you press <space>, or the 45-second timer expires, BOYAN cycles the current dialing attempt with the Cycle Dialing Auto- macro; adds or updates the number in the redialing queue; and then returns you either to the dialing directory or to terminal mode, depending on how you have configured the "Return to Dial Dir if no connect" option (section 3.5). 4. If the modem returns one of the no-connect messages (section 3.7): BOYAN adds or updates the number in the redialing queue, and then returns you to either the dialing directory or to terminal mode as you have configured. 5. If BOYAN detects carrier or sees the connect message: you have connected! If the auto-speed-detect feature is on, BOYAN checks the connect message and sets the baud rate appropriately. It then starts an elapsed-time-of-call timer. If the number was dialed by a directory code, then the appropriate BOYAN Action Module is invoked, and the linked logon script file will take control if one was specified. BOYAN also displays the last date you connected to this system. Finally, if this number was in the redialing queue (section 4.2.4), it is removed from the queue. BOYAN then returns control to you. 4.2.1.4: BOYAN Command Capabilities 43 ________________________________________________________________________ BOYAN's ability to dynamically add and delete numbers from the redialing queue is very powerful. Instructions for redialing from the queue with the <Alt-Q> command are in section 4.2.4. 4.2.1.4 Dialing Directory Options BOYAN can maintain multiple dialing directories of 200 entries each for your most frequently-dialed systems. The directory display consists of the directory page number, a chart of 20 of the system entries, and a brief help line. For each entry, BOYAN displays its name, phone number, BOYAN Action Module letter, logon script file name, default protocol, baud rate, parity setting, and last connect date. BOYAN also maintains a separate .PWD file which stores a private password for each entry. An entry's password is visible only when you select E to edit that entry, but a diamond in the "PW" column indicates that a password has been entered. BOYAN provides many options for maintaining the Dialing Directory; these are described below. If you delete an entry accidentally or make any other mistake while editing the Dialing Directory, you may use the Undo command to revert to the last-saved copy of the .FON file. After you exit the directory (by dialing a number or pressing <Esc>), BOYAN automatically saves all the changes you made, and they can no longer be undone. - <F1>: view Help Screen. - <Home>, <End>: Go to beginning or end of directory. - <UpArrow>, <DownArrow>: Move the scroll bar up or down. - <PgUp>, <PgDn>: Move scroll bar by page. - <Enter>: Dial the entry under the scroll bar. - <space>: Add the entry under the scroll bar to the Redialing Queue, or remove it from the Queue if it is already there. A small square next to the entry's code number indicates that the entry is currently in the Queue. - <Esc> or mouse right button: Return to terminal mode. - mouse left button: * single click: Set scroll bar at the mouse cursor position. * hold down and drag: Move scroll bar up or down with mouse. 4.2.1.4: BOYAN Command Capabilities 44 ________________________________________________________________________ * double-click on entry's name or phone number: Dial the entry. * double-click on entry's code number (at left edge of screen): Add/remove entry from Redialing Queue, like <space>. * single click on menu line: Select option from choices listed on line 24 of the screen. - <Alt+letter>: Move the scroll bar directly to the next entry whose system name starts with that letter. For example, press <Alt-E> to move the scroll bar down to the next entry starting with "E". - Alphabetize: Sort a range of entries by name, phone number, or last connect date. BOYAN offers three ways to sort: Name Increasing order by System Name. Phone Increasing order by phone number, with short (local) numbers preceding longer numbers. Date Decreasing order by last connect date. Note that BOYAN version 5 Dialing Directories do store the year as well as the month and day of the last connection. Finally, specify the first and last entries in the range to be sorted. The sorting process may take several seconds to complete. - Baud rate fill: To change the baud rate setting for a consecutive range of entries all at once, press B. Specify the range to fill; then select the desired baud rate by pressing <space> repeatedly and then <Enter>; or, if you prefer, select by digit: [3]=300, [1]=1200, [2]=2400, [4]=4800, [9]=9600, [0]=19200, or [8]=38400. - Clone directory: This command creates a new .FON file whose contents are exactly the same as the current Dialing Directory. Use the NewFON option to create a new, empty .FON directory. - <Del>: Delete the single entry under the scroll bar. The entry is saved to BOYAN's "clipboard." Later, you can use <Ctrl-P> to "paste" the entry back into the directory or even into a different Dialing Directory. Combined with the <Ins> command, this provides a handy way to move an entry wherever you want in the directory. - Delete range: Specify the first and last entries in the range to delete. Those entries and all entries between them will be deleted, and the rest of the directory entries will shift up to their place. (Also see the <Ctrl-X> "Exchange ranges" command.) To undo a mistaken Delete, press U immediately! 4.2.1.4: BOYAN Command Capabilities 45 ________________________________________________________________________ - Edit selected entry: use the cursor keys to highlight an entry for editing, then press E.. You will prompted to edit each field of the entry. While entering/editing an entry, all of BOYAN's normal Line Editor commands (section 2.4.5) are valid, as well as: <Enter> continue forward to the next field; <UpArrow> return to the previous field; <PgDn> accept the entry; and <Esc> abort the changes you have made. The fields for each entry are: System Name The system's name, for your own reference. Phone Number The full phone number. Special commands may be included within the number: - If you wish to use a long-distance dialing prefix, you may insert a Shortcut macro as described in section 4.2.1.5. - To make the modem pause during dialing, insert a comma wherever you want a pause to occur, e.g.: 9,,555-1212. - To select BOYAN's alternate dialing command for this system, append the letter a to the end of the phone number, e.g.: 730-2917a. After you press <Enter>, the a will appear as the character ª. The letter "a" is not actually sent to the modem as part of the phone number; rather, it signals BOYAN to use Macro #2 instead of Macro #1 when dialing this system. To learn how to configure dialing command macros, see section 3.9.3. BAM (BOYAN Action Module) A single letter to assign a special BAM to this entry, or just a space to use the default BAM. If you wish to specify a special BAM, choose from the list on Help Screen F (press <F1> to view). Action Modules are described in section 4.3. Script The name of an auto-logon script file, which BOYAN will automatically run whenever you connect to this system. (BOYAN can "learn" such script 4.2.1.4: BOYAN Command Capabilities 46 ________________________________________________________________________ files automatically; refer to section 4.7.3.) If you have not created a logon script for the entry, you should simply leave the "Script" field blank by pressing <Enter>. Prot (Protocol) A single letter to choose a default file transfer protocol to be used on this system, or just a space to not select a special default. Choose from [X]=Xmodem, [A]=ASCII, [Z]=Zmodem, etc. (see section 4.4.1 for the complete list). Note that your selection here is just a default, and does not prevent you from using other file transfer protocols when connected to this system. Comm (Baud Rate) You must select a modem speed to be used when dialing this system. Press <space> repeatedly until the desired baud rate appears; or, if you prefer, select by digit: [3]=300, [1]=1200, [2]=2400, [4]=4800, [9]=9600, [0]=19200, or [8]=38400. Comm (Parity) Select a parity setting to be used when dialing this system: [N]=None, [E]=Even, or [O]=Odd. [N]one is standard on most Bulletin Board Systems, while [E]ven is usually preferred for connecting to mainframes and services such as CompuServe. PW (Password) When you reach this field, the "Password:" prompt will appear. Type in the personal password that you use with this system. After you press <Enter>, only a small diamond will appear in the PW column to indicate that the password is tucked away there. Passwords are stored in a separate .PWD file, so your .FON file may still be shared freely. While online, you can have BOYAN type out this password by pressing <F3>. If you leave the PW field blank, then <F3> will refer instead to the default password entered in Config Area <S>. - File to disk: This creates a nicely-formatted disk file of a range of your Dialing Directory. The text file formed will be suitable for later printing, uploading, or viewing. BOYAN will prompt you to enter the file's name, with NUMBERS.TXT as the default (section 3.6). - Grab phone # from terminal screen: Another BOYAN exclusive! When you're online and you see a message like "Try Ed's BBS at (301)-854-3076", there's no need to find a slip of paper and a pen, 4.2.1.4: BOYAN Command Capabilities 47 ________________________________________________________________________ copy down the number, and then type it in to the Dialing Directory manually. Instead, simply move the scroll bar to a blank entry in the directory and type G. BOYAN will scan the terminal screen from bottom to top, "grab" the first valid phone number it finds, and insert it into the phone number field. If there is more than one valid phone number on the terminal screen, you may press G repeatedly to cycle through all of them. - <Ins> or Insert: This command inserts a single blank entry at the position of the scroll bar. - Locate: Scan the dialing directory for an entry. At the "LOCATE:" prompt, type in a part of the desired entry and press <Enter>. You can locate any part of an entry's name, phone number, etc. If a match is found, it is highlighted on the screen. To continue scanning the directory for further matches, press L again and <Enter>. Also see the <Alt+letter> command, described above. - NewFON: Change to a different FON directory, or create a new FON directory. Using multiple phone directories gives you a convenient way to organize your phone lists. For example, you might create a VOICE.FON directory for storing regular voice phone numbers, or a special LONGDIST.FON directory just for long-distance numbers. At the "New .FON file:" prompt, type a name of up to eight characters (it is unnecessary to include the .FON filename suffix). If BOYAN finds a .FON file of that name, that .FON file will be loaded. If BOYAN cannot find a file with the name you specified, you will be asked if you mean to create a new .FON directory with that name. Press "Y" to verify, and an empty phone directory will be created. - Print: Print a nicely-formatted range of the directory. Enter the code numbers of the first and last entries in the range to print. You are given the opportunity to set up the printer using BOYAN's printer interface (section 4.5.4) before printing begins. - <Ctrl-P>: Paste the clipboard entry back into the dialing directory. The clipboard stores the last entry deleted with the <Del> command. - Queue: Enter the Redialing Queue. A handy trick is to use the cursor keys and <space> to mark entries for queue redialing, and then hit Q to invoke the Queue. Note that the Q key returns to the Dialing Directory from the Redialing Queue as well, so you can use Q to switch back and forth. - Save: Force the Dialing Directory to be saved. You won't normally need to use this command, since BOYAN saves your changes to the .FON file automatically when you exit the Dialing Directory (either by pressing <Esc>, invoking the redialing Queue, or dialing a number). 4.2.1.4: BOYAN Command Capabilities 48 ________________________________________________________________________ - Undo: Revert to the last-saved copy of the current FON file. You must use this command before exiting from the Dialing Directory, because BOYAN automatically saves all modifications then. - eXchange: Press X to exchange any two entries. This is convenient when, after alphabetizing with the A command, you wish to put a favorite system at the top of the list. Simply specify the code numbers of the two entries to swap. - <Ctrl-X> block exchange: This command allows you to exchange two whole ranges of the dialing directory; for example, you could swap entries 1-10 with entries 11-20. You are prompted for the top and bottom of the first range and the top of the second range. The ranges you specify should not overlap. Each dialing directory is automatically saved to disk after any changes you make to it. Be sure that you do not remove the disk containing your .FON directory at any time while using BOYAN. 4.2.1.5 Long-Distance Dialing Prefixes Phone numbers are processed as macros; that is, when BOYAN dials, it treats the phone number as a macro. Thus any macro command (see section 3.9 and chapter 5) can be embedded within a phone number. BOYAN's Shortcut macro commands are an example. If you use a long-distance service with codes too long to fit in the directory, this is your solution. Suppose you belong to a long-distance service which requires you to dial a local number (say 765-4321), pause, and enter a seven-digit code (say 1234567) before dialing the long-distance number itself. In BOYAN's Config Area <M>, assign the \* Shortcut (#18) to the string 765-4321,,1234567 . Then, wherever the backslash and asterisk are found embedded in a phone number, the above string will be substituted. For example, a directory entry with the phone number \*919-682-4225 will automatically use your long-distance service when it is dialed. All other macro commands are valid within phone numbers, as well. 4.2.1.6 Uniform Dialing Prefixes Another common situation is when the same BOYAN phone directory must be used both at home and at work. If the work phone requires a 9 and a pause before dialing out (e.g. Centrex), the most convenient way to implement this is to change the modem dialing command itself. This is done in macro #1 of Config Area <M> (section 3.9.3). 4.2.1.6: BOYAN Command Capabilities 49 ________________________________________________________________________ You can assign a single keystroke to modify the dialing command, using the \SM1 macro command (see section 5.2.16). Suppose you want to set it up so that pressing the <F9> key selects Centrex dialing, and pressing the <F10> key selects normal dialing. To do this, configure macro #79 <F9> to be \SM1[ATDT 9,"@SF{] and configure macro #80 <F10> to be \SM1[ATDT"@SF{] . Having done this, you can conveniently switch BOYAN from one dialing command to another with a single keypress. 4.2.1.7 Disable Call Waiting If you have call waiting, you are familiar with the friendly click you get when another call comes in. That click is not so friendly to modems, however, often causing them to lose the connection altogether. Most phone companies now offer you the ability to temporarily disable call waiting by dialing *70 immediately before the number itself. (On a pulse phone, you dial 1170.) To make BOYAN automatically disable call waiting each time it dials the modem, change the Dialing Command (macro #1) to: ATDT*70,@SF{ If you do not have Touch-Tone service, the Dialing Command would be: ATDP1170,@SF{ 4.2.2 <Alt-H> Hang Up Modem Press <Alt-H> to hang up the modem. The procedure BOYAN uses for hanging up the modem is completely specified in Macro #4 (see section 3.9.3). BOYAN will report "Hangup successful" or "Hangup unsuccessful" after trying. 4.2.3 <Alt-P> Parameter Change BOYAN version 5 supports 4 serial ports (Com1 through Com4), seven modem speed rates (300, 1200, 2400, 4800, 9600, 19200, and 38400), and 3 parity formats (none, even, and odd). When BOYAN starts, it sets these three variables to the values specified in Config Area <C> (section 3.7). If you dial a number from the dialing directory, BOYAN will automatically set the modem parameters; however, if you wish to change the parameters manually, you may use the <Alt-P> command. Pressing <Alt-P> brings up a menu of key options, enabling you to change serial port, modem speed, or parity. When the Status Line displays the desired parameters, press <Enter> for BOYAN to make the change. If you 4.2.3: BOYAN Command Capabilities 50 ________________________________________________________________________ press <Esc> during this process, BOYAN will return to its previous parameters. Technical note: When you select No parity, BOYAN automatically sets the line format to 8 data bits, 1 stop bit. When you select Even or Odd parity, the line format is 7 data bits, 1 stop bit. Since these combinations are standard, BOYAN makes the choice automatically to avoid confusion. Also note that BOYAN runs the "Reset Modem Parameters" Auto-macro (#3) anytime you change the baud rate or parity with <Alt-P>. 4.2.4 <Alt-Q> Queue Redialing BOYAN's Redialing Queue is one of its easiest and most powerful features. The queue will repeatedly dial from a list of numbers until one connects. Systems which you have dialed with the <Alt-D> command without connecting are automatically added to the queue. If you later dial the system again and do make a connection, BOYAN removes the number from the queue. Up to twenty different systems can be in the queue at one time. Press <Alt-Q> from BOYAN's terminal mode. The display lists each system which is currently in the queue, along with the number of attempts made so far, the length of time in the queue (Q-time), and the current status. BOYAN provides the following commands for you to use in the Queue: - <F1>: for detailed help with Queue commands. - To add a number to the Queue which is not in the dialing directory, simply type the full number manually and press <Enter>. - To add a number to the Queue which is in the dialing directory, simply type the system's code (1-200) and press <Enter>. - <Home>, <End>: Go to top/bottom of Queue. - <UpArrow>, <DownArrow>: Move the scroll bar up or down. - <Esc> or mouse right button: Return to terminal mode. - <space> or <Enter>: begin redialing. Starting with the number under the scroll bar, BOYAN will dial each number in turn, waiting for modem messages just as after dialing with <Alt-D> (section 4.2.1.3). After dialing the last number in the Queue, it returns to the top to run through the list again. BOYAN pauses for 3 seconds after every unsuccessful redial (to change this, see section 3.8). During this pause, pressing <Esc> will stop redialing and return to the Queue display, pressing <space> will manually cycle BOYAN to the next 4.2.4: BOYAN Command Capabilities 51 ________________________________________________________________________ number in the Queue, and pressing D will delete the number just dialed from the Queue. - mouse left button: * single click: Set scroll bar at the mouse cursor position. * hold down and drag: Move scroll bar up or down with mouse. * double-click on entry's name or phone number: Begin redialing at the entry. * single click on menu line: Select option from choices listed on line 24 of the screen. - <Alt+letter>: Move the scroll bar directly to the next entry whose system name starts with that letter. For example, press <Alt-E> to move the scroll bar down to the next entry starting with "E". - Clear: clear the entire queue. You will have to verify your decision by pressing Y. - <Del> or Delete: Delete the entry under the scroll bar from the Queue. The entry is saved in BOYAN's Queue Clipboard. - <Ctrl-P> or Paste: "Undelete" the last Queue entry deleted, inserting it at the current position of the scroll bar. Using the D and P keys, you can precisely arrange the order in which systems are redialed. - Quit to Dialing Directory: It is often convenient to add and delete entries from the Queue directly from the Dialing Directory. While in the directory, you may mark and unmark entries for the Queue by either pressing <space> or, if you have a mouse, double-clicking on the entry's code number. A small square next to the code number indicates an entry that is currently in the Queue. Press Q again to return to the Queue Redialer. When BOYAN detects a connection with one of the systems it has dialed, the redialing screen will disappear and a "ringing" alarm will sound. Press any key to stop the alarm. If the connected system has an auto- logon script specified in the dialing directory, the alarm will stop automatically after 10 seconds (the script keyboard timeout, section 3.8) so the script file can begin processing. The connected system is automatically deleted from the queue, so after you have finished your session, you may press <Alt-Q><space> to redial the remaining systems. 4.2.5: BOYAN Command Capabilities 52 ________________________________________________________________________ BOYAN's Macro Language provides powerful tools for manipulating the Queue; for instance, the ability to add and delete systems from the Queue by name. Please see section 5.2.9 for details. 4.2.5 <Ctrl-End> Send Modem Break Signal Some mainframe systems recognize a special signal called a "modem break." Press <Ctrl-End> to send this signal. This command also purges BOYAN's buffer of incoming text. 4.2.6 <Del> Send DEL character Some mainframes expect the DEL character (ASCII code 127) rather than the normal backspace character (control-H) for backspacing. To generate this character, press <Del>. If you need to use this character frequently, you may wish to "swap" the backspace and <Del> keys as described in section 3.10.2. If you do this, the backspace key will send ASCII code 127, and the <Del> key will send a normal control-H character. 4.3 BOYAN Action Modules At all times during communications, both what you type and what the remote system sends back are processed according to a BOYAN Action Module. Terminal emulations, gossip mode, and host mode are all examples of BOYAN Action Modules. There is exactly one Action Module active at all times. The name of the currently active Action Module is displayed on the main command menu, which you can view at any time by pressing <F1>. 4.3.1 <Alt-A> Activate new Action Module Pressing <Alt-A> brings up a menu of all the available Action Modules. To select a module, touch the appropriate letter or digit, e.g., G for Gossip. Press <Esc> to return to the communications screen without changing the current action module. 4.3.2 <Alt-Equals> Previous Action Module This key automatically activates the Action Module which was in use prior to the current BAM. 4.3.3: BOYAN Command Capabilities 53 ________________________________________________________________________ 4.3.3 <Scroll-Lock> Switch Between BOYAN/Terminal Keysets During normal BOYAN operations, all of the function keys and cursor keys are assigned to BOYAN commands and user-definable macros; for example, the <UpArrow> key normally invokes BOYAN's scroll-back buffer. However, when BOYAN is emulating a terminal such as VT-100, it is convenient to have your keyboard's <UpArrow> simulate the real VT-100 <UpArrow> key. Therefore, BOYAN's terminal emulations come with "secondary" or "terminal" keysets. To switch between BOYAN's normal keyset and the terminal keyset, press <Scroll-Lock>. While <Scroll-Lock> is locked, 2 the secondary keyset is active, and a small indicator appears in the middle of the status line. (On certain Tandy computers with no <Scroll-Lock> key, use <Alt-NumLock> instead.) Both the primary and secondary keysets are completely customizable. See section 3.9 and Appendix D. 4.3.4 Action Module Descriptions 4.3.4.1 ADM-3A, IBM-3101, TVI-925, and VT-52 Emulations BOYAN emulates all the screen-handling operations of these common terminals. In addition, each provides its own user-definable secondary keyset which mimics the terminal's function and cursor keys. While <Scroll-Lock> is locked, the <Alt-1>, <Alt-2>, etc. keys correspond to the terminal's function keys, and your cursor keys correspond directly to the terminal's cursor keys. Please see section 3.10.2 for details about terminal configuration options. 4.3.4.2 ANSI-BBS Emulation The ANSI-BBS module is useful for connecting to Bulletin Board Systems. Many BBS programs send special "ANSI" sequences to display colorful welcome screens, etc., which BOYAN will handle appropriately if the ANSI-BBS Action Module is selected. When <Scroll Lock> is locked, the cursor keys send special control sequences--great for the full-screen message editors offered by some BBS's. Technical note: BOYAN does not require that you install the DOS ANSI.SYS driver in memory; the codes are handled internally. 4.3.4.3 CONTROL Action Module The CONTROL module is a convenient tool that makes all hidden "control characters" visible. ASCII characters 0 through 31 are represented as ^00, ^01, ^02, .. ^31. Two exceptions are ASCII 13, which is represented j as a {, and ASCII 10, which is represented as a . Note that any 4.3.4.4: BOYAN Command Capabilities 54 ________________________________________________________________________ translation or filtering done by your Translation Table (section 4.1.7) occurs before the control characters are displayed. 4.3.4.4 DOORWAY Module The DOORWAY module does two things: first, it removes BOYAN's Status Line from the screen altogether; and second, it sends any key you press (including "extended" key codes such as function keys) directly over the modem. All BOYAN command keys except for <Alt-Equals> are unavailable during DOORWAY mode. The <Alt-Equals> key retains its normal BOYAN function of returning you to the previously-selected Action Module, from which normal BOYAN commands will be accessible. 4.3.4.5 DUMBTERM (Dumb Terminal) This BAM makes BOYAN act as a "dumb terminal." No special codes are processed; all incoming characters from the modem except control characters are displayed on the screen as-is. 4.3.4.6 GOSSIP Mode BOYAN provides a gossip mode for direct "chatting" with the person on the other side of your connection. When the GOSSIP BAM is invoked, the echo keyboard toggle is automatically turned ON, and the screen is split into two parts. The upper, larger part displays incoming text only, while the lower part displays the text which you type. All BOYAN commands are still available during gossip mode. To leave gossip mode, you must select a different action module, at which point the echo keyboard toggle is returned to its previous setting. 4.3.4.7 HOST Action Module The HOST action module works in conjunction with the HOST.BSC script file in order to provide BOYAN's host mode. A complete explanation of how to use the host mode is in section 4.8. 4.3.4.8 VT-100 Emulation The DEC VT-100 terminal is an extremely popular terminal, used for linking up with Digital Equipment Corporation's mainframe computers as well as many other mainframes. BOYAN's VT-100 action module supports nearly all of the VT-100/VT-102 functions, including region scrolling, display attributes (including extension to ANSI colors), programmable tabs, block graphics, and dedicated printing. Dedicated printing gives the remote system control of your local printer: when dedicated print mode is triggered by the <Esc>[4i sequence, all subsequent text is echoed to your printer rather than to the screen. The <Esc>[5i sequence stops dedicated print mode. The 4.3.4.8: BOYAN Command Capabilities 55 ________________________________________________________________________ following Unix batch file uses dedicated printing to print files to your computer's printer: echo -n <Esc>[4i cat $1 echo -n <Esc>[5i If you insert a "?" character between the [ and the 4 and 5, then BOYAN will echo the text to both your screen and printer. The VT-100 secondary keyset has been tailored for use with Unix's Emacs editor. Please see Appendix D for a complete description of the VT-100 key definitions and how to customize them. 4.4 BOYAN File Transfers 4.4.1 Internal Protocols One of the most frequent activities during communication is transferring files. Sending a file from your PC to the remote computer is called uploading; receiving a file from the remote computer is downloading. It is possible to transfer a file by simply sending its contents directly, but sometimes phone line "noise" can cause fatal errors during the transfer. Various "protocols" have been developed to check for, and correct, those errors. BOYAN version 5 supports the following file transfer protocols internally: Xmodem Very widely used; good error-checking with the checksum method. Relaxed Xmodem Identical to Xmodem, but with relaxed timing for networks such as CompuServe. CRC-Xmodem An enhancement to Xmodem that improves error- checking with the Cyclic Redundancy Check method. 1K-Xmodem Just like CRC-Xmodem, except the data is checked for errors less often. This is very fast over "clean" phone lines, but slow if there is a lot of line noise. It will automatically convert to CRC- Xmodem in mid-upload if there are too many errors. This protocol is sometimes (incorrectly) referred to as "Ymodem." Ymodem Ymodem is identical to 1K-Xmodem, except that it adds a "header block" so that the receiver knows in advance the name and the size of the file being 4.4.1: BOYAN Command Capabilities 56 ________________________________________________________________________ transferred. (This Ymodem is for single-file transfers only. However, BOYAN can use Chuck Forsberg's DSZ program to perform "batch" Ymodem transfers.) G-Ymodem This variant of Ymodem is very fast but does no error-checking. It is meant to be used on modems with their own built-in error-checking protocols, such as MNP. G-Ymodem can also be used with the "1K-Xmodem-G" protocol available on some PC-Board systems, but allow about ten extra seconds for handshaking as the transfer starts. ASCII This is the fastest protocol of all, but there is NO error-checking. It may only be used with text files. Generally, if the accuracy of the transfer is important, this method should not be used. Message Upload This is a "smart" ASCII variant that BOYAN uses only for uploading messages. You can save time and money by preparing messages with your word processor instead of typing on-line. See section 4.4.5 for details. 4.4.2 External Protocols Many sophisticated protocols are supported by standardized programs on the IBM-PC. Jan van der Eijk's PCKERMIT.EXE, for example, is the standard for the Kermit protocol, widely used on mainframes. Analogously, Chuck Forsberg's DSZ.COM is the standard for Zmodem. BOYAN integrates standard programs like these to perform so-called "external protocol transfers." Updated versions of these programs may be found on many IBM-PC Bulletin Board Systems, including the BOYAN Support BBS. Any external protocol can be configured to run through BOYAN (section 3.12). BOYAN offers built-in support for the external protocols listed below. To use any of these protocols, simply copy the protocol's .COM or .EXE file (given in parentheses below) into your external protocol directory, e.g. C:\BOY5\PROT. You do not need any extra batch files. The external protocols appear on BOYAN's menus just like the internal protocols. Bimodem (BIMODEM.COM) This protocol offers simultaneous uploading, downloading, and chat. You will want to assign a function key to the macro \DC-[%P:BIMENU] (see section 3.9.4); this function key will then invoke BiMenu for setting up the transfer. After you return to BOYAN, the transfer will start without your having to type anything, since Bimodem 4.4.2: BOYAN Command Capabilities 57 ________________________________________________________________________ supports auto-downloading (described in section 3.12.1). Compuserve-B (OZBEXT.EXE) The Quick-B protocol available on CompuServe. Supports auto-downloading. Kermit (PCKERMIT.EXE) Widely used on mainframe systems. Megalink (MLINK.COM) A streaming variant of Xmodem developed by Paul Meiners. MPt (MPT.EXE) A friendly, fast protocol developed by Matthew Thomas (read "Em-point"). Supports auto- downloading. SEAlink (CLINK.EXE) An enhancement to Xmodem developed by System Enhancement Associates. Ymodem-batch (DSZ.COM) Like BOYAN's built-in Ymodem, but supports batch transfers. Zmodem (DSZ.COM) The new "standard" protocol for both Bulletin Board and Unix systems, developed by Chuck Forsberg. Very fast and reliable, and supports auto-downloading. Many external protocols allow "batch transfers"; that is, the transfer of multiple files during a single invocation of the external program. BOYAN handles batch downloads automatically. To specify a batch upload, you may either 1) enter multiple filenames at BOYAN's "FILENAME:" prompt, e.g. FOO.EXE BOY*.ZIP BAR.DOC; or 2) use the File Manager to tag multiple filenames directly from a disk directory, as described in section 4.6.1. Important note: the external protocols listed above are all copyrighted ShareWare products, with licensing agreements independent of that of BOYAN Communications. Please register those that you use with their respective authors! 4.4.3 Auto-Find Filename Feature BOYAN has the unique feature of being able to automatically determine the name of the file you wish to transfer based on what you have told the remote computer. Other communications programs require you to type the full filename twice. Only filenames with a three-letter suffix (e.g. TWIDDLE.ARC) can be found this way; if you want to send a file named TEST.X, you will have to retype the filename for BOYAN. You may disable this feature if you wish (section 3.7). 4.4.4: BOYAN Command Capabilities 58 ________________________________________________________________________ 4.4.4 <PgUp> Upload File This is the procedure you should follow for uploading a file from your PC to a remote system: 1. From BOYAN's terminal mode, tell the remote system that you wish to upload a file. As it prompts, enter the file's name and the upload protocol you wish to use. 2. When the remote system says it is ready to receive, press the <PgUp> key. (Alternatively, you may press <Ctrl-PgUp> to select the file(s) straight from a file directory list. See section 4.6.1.) 3. From the menu of protocols, press the letter corresponding to the same protocol you told the remote system you would use, or press <Enter> instead to use the default protocol. 4. In its upload window BOYAN will display the directory path and filename of the file to be transferred. If the file you wish to upload is not in the path displayed, press the <UpArrow> key, edit the pathname, and press <Enter>. Make sure the filename(s) are correct and press <Enter>. The transfer should begin. 5. To abort the upload procedure at any time, press <Esc>. With BOYAN's internal protocols, a bar to the left of the upload window graphically indicates the percentage of the file transfer completed. 6. When the transfer finishes, successfully or unsuccessfully, BOYAN will sound an alarm and return you to terminal mode. If the upload was successful, the total transfer time and transfer efficiency will also be displayed. The efficiency is based on a pure transmission at full speed, so any figure above 75% is quite good. 4.4.5 Uploading a Message If you write a message using your word processor, SideKick, or any other ASCII text editor, BOYAN can upload it just as if you had typed the message directly. First, from terminal mode, tell the remote system you wish to enter a message; enter all header information such as addressee, subject, etc. When you are given the prompt for the first line of the message, press <PgUp>. Select Message Upload as the protocol. You will have to enter the message's filename manually. BOYAN provides a degree of convenience in message uploading not found in any other communications program. First, it automatically determines the remote system's line prompt; press <Enter> to verify. (This field 4.4.5: BOYAN Command Capabilities 59 ________________________________________________________________________ may be left blank if the remote system does not give you a new prompt for every line of the message.) Then watch as BOYAN "types" the message. BOYAN automatically adds a space to any blank lines, because most systems interpret a blank line as the end-of-message signal. If you have turned the "Auto-Detect Word Wrap" feature ON (section 3.7), it will automatically detect an incoming <Return> character and assume that the remote system has "word-wrapped." In that case, BOYAN will send the line without a <Return> character. This feature means that you do not need to tailor your prepared messages to the system's maximum line length; if the system word-wraps, BOYAN will take care of it for you. Not all systems can accept the message text as fast as BOYAN can send it. To slow BOYAN down, increase the inter-character pacing delay in Config Area <E> (section 3.8). 4.4.6 <PgDn> Download File Follow the procedure below to download a file from the remote system to your PC: 1. From BOYAN's terminal mode, instruct the remote system that you wish to download a file. As it prompts, enter the file's name and the download protocol you wish to use. If the protocol you selected supports auto-downloading (e.g., Zmodem or MPt--see section 3.12.1), then sit back and relax; BOYAN will start the download automatically. Otherwise... 2. When the remote system says it is ready to send, press <PgDn>. 3. From the protocol menu, select the menu letter of the same protocol you told the remote system you would use. Or, press <Enter> to accept the default protocol. 4. The next step varies a little, depending on whether the protocol needs to be told the download filename. a. If you are using one of BOYAN's built-in protocols, such as Xmodem or ASCII, BOYAN's "Auto-Find Filename" feature will determine the name of the file to be downloaded. In the download window, BOYAN displays the filename as well as the directory pathname. Press <UpArrow> if you wish to edit the drive/directory into which the file will be downloaded. When the path and filename are correct, press <Enter> at the "FILENAME:" prompt. For ASCII downloads, you may have to press <Enter> one more time to signal to the remote system that you are ready. The transfer will begin. 4.4.6: BOYAN Command Capabilities 60 ________________________________________________________________________ b. Alternatively, if you are using an external protocol such as Kermit, you do not have to enter the filename at all-- the protocol takes care of that. You still have the chance to modify the drive and directory which will be used for the download. Press <Enter> at the "PATH:" prompt; the transfer will begin. 5. Press <Esc> at any time to abort the download. For Ymodem-type downloads, a bar to the left of the upload window graphically indicates the percentage of the file transfer completed. 6. When the transfer finishes, BOYAN sounds a brief alarm. If the download was successful, the total transfer time and transfer efficiency will also be displayed. The efficiency is based on a pure transmission at full speed, so any figure above 75% is quite good. You will find that BOYAN's transfers almost always take less time than the remote system predicts they will! 4.5 Session Logging 4.5.1 <Alt-L> Log to Disk Toggle Press <Alt-L> to log all incoming text to a disk file. You will have to enter the log file's name, or just hit <Enter> to accept the default (section 3.6). If the file exists, BOYAN will append the new text to the end of the file. When you begin logging, BOYAN runs the "Log file init" Auto-macro, which adds a one-line status message to the log file giving the time and date. Press <Alt-L> again to stop disk logging. Note that BOYAN's Scroll-Back buffer offers a convenient alternative to the <Alt-L> command: at any time, you can scroll back through the text of your session, and selectively mark regions to be filed to disk. The Scroll-Back buffer is described in section 4.7.2. 4.5.2 <Alt-S> Save Screen Image to Disk Press <Alt-S> to save the current screen to a disk file. This file's directory and filename are configurable (section 3.6). Each time a screen is saved, BOYAN appends a one-line header and the screen image to the end of the file. 4.5.3: BOYAN Command Capabilities 61 ________________________________________________________________________ 4.5.3 <Alt-U> Toggle BOYAN.USE Usage Log File BOYAN automatically maintains an activity log file. Unless you change the configuration, the activity log will be called BOYAN.USE and will be saved in the BOYAN home directory. The log keeps track of the following: - The date, time, and length of all system connections made with BOYAN. - All non-batch file transfers, including the filename, protocol name, and transfer efficiency percentage. (For information on how to record Zmodem batch transfers in the usage log, please refer to Appendix A.) BOYAN's Auto-macros allow you to completely customize the format and contents of the activity log. For example, you could customize BOYAN to use the CDS (Call Data Standard) format for its usage log. Please see sections 3.9.3 and 3.6 for configuration information. 4.5.4 <Ctrl-PrtSc> Printer Log Toggle After you press <Ctrl-PrtSc> all incoming text is logged (copied) to the printer. Before printing starts, however, BOYAN offers a brief status line menu of printer options: you can press I to run the printer Initialization macro; L to advance the printer to the next line; F to advance the printer to the next form (page); or M to "type" a brief message to the printer. When the printer is set up properly, press <space> for BOYAN to start printing. To stop printer logging later, press <Ctrl-PrtSc> again. (Section 3.9.3 describes how to customize the printer initialization macro.) 4.5.5 <Shift-PrtSc> Save Screen Image to Printer As always, the <Shift-PrtSc> command will copy the entire current screen to the printer. 4.6 DOS and File Commands 4.6.1 <Alt-F> The File Manager BOYAN houses a complete integrated file manager. To invoke it, press <Alt-F> from terminal mode. BOYAN will read, alphabetize, and display the names of the files found in the current directory. Names of subdirectories of the current directory are also displayed, surrounded by arrows. The free disk space is shown on the top line of the screen 4.6.1: BOYAN Command Capabilities 62 ________________________________________________________________________ (unless you disable this feature in configuration--see section 3.7). BOYAN handles up to 350 files in each subdirectory. At the bottom of the screen, you will see a menu of key options: Newdir Mark Send Upload Info List Fon Copy Del Exec Ren View Word Additional, unlisted options are Pattern, <Ctrl-P> = unmark pattern, Y = show free space, and <Ins> = issue DOS command. However, these commands will be listed on the help screen if you press <F1>. Note: the Copy, Delete, Execute, Rename, View, and Word processor commands are only available if there is enough memory for a DOS shell (see section 3.5). Most File Manager commands, such as Copy and Upload, may be applied to multiple "marked" files at a time. Use the space bar or the M key to selectively mark files for the operation; then select the command. In any DOS command, the symbol [marked] will be successively replaced by each of the marked filenames. For example, the command "COPY [marked] A:" will copy each marked file to the A: drive. Select from among the following commands: - <F1>: View help screen. - <Esc> or mouse right button: Return to terminal mode. - cursor keys: Use the four arrow keys to move the highlighted file bar from file to file. Press <Home> to go to the beginning of the directory, and <End> to go to the end. If there are more than 100 files in the directory, press <PgUp> and <PgDn> to change pages. Finally, use the <Ctrl-PgUp> and <Ctrl-PgDn> key combinations to move to the top and bottom, respectively, of the current column. - <Alt+letter>: Move the highlight bar directly to the next filename which starts with that letter. For example, pressing <Alt-E> would jump the highlight to the next filename starting with "E". - <space> or Mark: Set/unset a "mark" on the current filename. Mark as many files as you like within the directory. - <Enter>: If the highlight is on a subdirectory name, pressing <Enter> enters that subdirectory. On the other hand, if the highlight is on a filename, then the <Enter> key selects the current "default File Manager option." This default option depends on which BOYAN command is making use of the File Manager. For example, the <Ctrl-PgUp> upload command invokes the File Manager with a default option of U, so that to upload the marked files you need only press <Enter>. 4.6.1: BOYAN Command Capabilities 63 ________________________________________________________________________ - mouse left button: * single click: Set highlight bar at the mouse cursor position. * hold down and drag: Move highlight bar with mouse. * double-click on filename: Same as pressing <Enter>. * single click on menu line: Select option from choices listed on line 24 of the screen. - Copy: Press C to copy file(s). Type the target for the copy and press <Enter>. Note: you may print any file by copying it to the file PRN . - Delete: To delete file(s), press D. As with any other command, press <Esc> to abort or <Enter> to accept. - Execute script: Press E to execute the highlighted .BSC file (BOYAN script file). - Execute file(s): To invoke .EXE, .COM, or .BAT file(s), press E. You may add any command line parameters to the end of the filename before pressing <Enter>. - FON file: If the highlight is on a .FON file in your FON file directory, then press F to activate that file as your current Dialing Directory. - Info about file size: Pressing I gives the size of the current file in bytes, and the approximate length of time it would take to transfer the file at the current baud rate. If your port speed is 19200 or 38400 baud, then the estimate will be based on the speed given in your modem's "CONNECT xxxx" message, even if BOYAN's Auto- Detect baud rate feature is OFF. - List filename(s) to BOYMARK.LST: Selecting L quits the File Manager and creates a BOYMARK.LST file in the current directory containing a list of all the marked filenames, including the full path specification for each. If no files are marked, then BOYMARK.LST will contain the name of the single highlighted file. - New directory: When you press N you will be given a new "DIR" prompt so you can change drives, directories, or file specifiers. If the highlight was on a subdirectory name, you can just press <Enter> to select that subdirectory for viewing. 4.6.1: BOYAN Command Capabilities 64 ________________________________________________________________________ - Pattern mark: Use this command to mark many files at once. For example, to delete all files with a suffix of .BAK, you would type P, *.BAK <Enter>, D <Enter>. - <Ctrl-P> pattern unmark: Use this command to unmark many files at once. For example, to delete all files except those with a suffix of .BAK, you would first mark all files with P <Enter>, then unmark the .BAK files with <Ctrl-P> *.BAK <Enter>, and finally delete the remaining marked files with D <Enter>. - Rename: Press R to rename file(s). Then type the new name for the file and press <Enter>. - Send filename(s) over modem: Press S to send filename(s) directly to the modem, as if you had typed them by hand. BOYAN adds a <CR> after each filename. - Upload file(s): Press U to upload a file or files. If no files are marked, BOYAN simply opens the Upload Window for the highlighted file so you can select a protocol and upload the file (section 4.4.4). If multiple files are marked, BOYAN lists those filenames to BOYMARK.LST, then enters the Upload Window with a default filename of @D:BOYMARK.LST (where d is the current drive letter). Several external protocols--including Zmodem, batch-Ymodem, and MPt--will handle such a file list properly, uploading each of the files in turn. Note: this is the default command if you enter the File Manager by pressing <Ctrl-PgUp> from terminal mode. - View: Press V to view the file(s) using the TYPE command or other command which you have substituted (section 3.6). - Word processor: Press W to edit the file using the TED program or other editor which you have substituted (section 3.6). - Y = Free space: press Y to display the amount of free space on the drive. (The free space is displayed automatically if the "Check Free disk space" setting is ON in Config Area <D>.) - <Ins>, Issue DOS Command: Press <Ins> to bring up the ">" prompt. Type any DOS command and BOYAN will execute it. If any files are marked, you may include the string [marked] in the DOS command; BOYAN will then create and execute a batch file where a marked filename is substituted for [marked] on each line. 4.6.2 <Alt-J> Jump to DOS If you have reserved enough memory for a DOS shell, pressing <Alt-J> will jump you directly into a DOS shell. From DOS, you may use your word processor, un-zip a file, or run your spreadsheet. When you are 4.6.2: BOYAN Command Capabilities 65 ________________________________________________________________________ ready to return to BOYAN, be sure the BOYAN disk is in the same drive it had been in before the shell, and type EXIT at the DOS prompt. BOYAN will return to your communication session as if you had never left it. 4.6.3 <Alt-N> New Default Drive/Directory To change the current logged drive or subdirectory, press <Alt-N> and enter the new path. Valid examples are B:, \MODEM\FILES, and c:\utility. 4.6.4 <Alt-V> View File To view the contents of an ASCII file, press <Alt-V>. When prompted, you may either directly type the name of a file to view, or press <Enter> to select from the File Manager. If you invoke the File Manager, you may use the space bar to select multiple files to view; then press <Enter> to view the file(s). You may configure the DOS command used by BOYAN for viewing files in section 3.6. 4.6.5 <Alt-W> Word Process (Edit) File To edit an ASCII file, press <Alt-W>. When prompted, you may either directly type the name of a file to edit, or press <Enter> to select from the File Manager. If you invoke the File Manager, you may use the space bar to select multiple files to edit; then press <Enter> to edit the file(s). You may configure the DOS command used by BOYAN for editing files in section 3.6. 4.6.6 <Alt-Y> Free Space on Disk Press <Alt-Y> to find the number of bytes of free storage space on any disk. Select the drive by letter, or just press <Enter> to see the free space on the current disk. 4.6.7 <Ins> Issue DOS Command If you have reserved enough memory for a DOS shell (see section 3.5), pressing <Ins> will bring up the ">" prompt. Type any DOS command or program name and BOYAN will execute it. 4.7.1: BOYAN Command Capabilities 66 ________________________________________________________________________ 4.7 Scroll-Back Buffer, Scripts, etc. 4.7.1 <Alt-R> Run Script File Almost any action BOYAN performs can be automated with the use of BOYAN Script Files. A BOYAN Script File is a series of macro commands stored in a normal text file. A full description of BOYAN's script language, along with appropriate examples, is in chapter 5. When you press <Alt-R>, you are prompted to enter the name of the script file to run. The script file takes control, replacing the BOYAN v5 message on the status line with its name. While the script file controls BOYAN, the only valid keyboard commands is <Esc>, which aborts the script. As you will learn in chapter 5, the commands within a script file can be organized into "blocks". To run just one of those blocks, respond with scriptname;blockname to the "SCRIPT:" prompt. For example, to run just the "logon" block of the "wildcat" script, you would press <Alt-R> and respond "wildcat;logon". Although programming scripts from scratch can be quite complex, BOYAN provides a facility which writes custom scripts for you. This facility, called "Script Learn," operates within BOYAN's Scroll-Back buffer. 4.7.2 <UpArrow> Scroll-Back Buffer BOYAN provides a unique Scroll-Back feature. After reserving memory for its own variables and the DOS Shell (section 3.5), BOYAN uses all remaining memory for the Scroll-Back Buffer, which traps all incoming text from the modem and "remembers" it so you can scan it later. BOYAN can often save thousands of lines of past text. Furthermore, the buffer remembers what YOU type. This is the trick which lets BOYAN automatically build script files for you, from a communications session which has already been completed! Press the <UpArrow> key to invoke the Scroll-Back Buffer. Your "current position" is at the bottom of the screen. A number in the top-right corner tells you which line of the buffer you are on. You now have the following options: - <F1>: detailed help. - <Esc> or right mouse button: exit the Scroll-Back Buffer and return to terminal mode. - <UpArrow>, <DownArrow>: scroll line-by-line through the buffer. 4.7.2: BOYAN Command Capabilities 67 ________________________________________________________________________ - <PgUp>, <PgDn>: scroll page-by-page through the buffer. - <End>: move to the end of the buffer, which shows the most recent communication. Press <End>, then <PgDn> to see the first page (oldest text) in the buffer. - <Home>: scroll back to the beginning of your last connection. Every time you make a connection, BOYAN places an invisible marker in the buffer. <Home> takes you back to each of these markers in turn. - mouse left button: * click and hold near top of screen: scroll up through the buffer. * click and hold near bottom of screen: scroll down through the buffer. * single click on menu line: Select option from choices listed at the bottom of the screen. - File: To file a region of text to disk, first mark the beginning of the region with the M command. Then use the cursor keys to place the last line of the region at the bottom of the screen. When you press F, you will be prompted to enter a filename (or press <Enter> to use the default; see section 3.6). The region will be appended to the disk file. - Go to mark: pressing G scrolls so that the marked line is placed at the bottom of the screen. - Locate: search for text within the buffer. You will be prompted for a string to locate. BOYAN's locate routine is not case-sensitive, so "bOyAn" will match "BoYaN". If the string is found, the buffer scrolls so the string is on the bottom line of the buffer, and the line is highlighted. To search back further in the buffer for other occurrences of the same string, press L, then <Enter>. - Mark: To use the scroll-back buffer's F, P, Q, and W commands, you must first mark the beginning of the region with the M command. Use the cursor keys to move the first line of the desired region to the bottom line of the screen. Then press M. The mark is set and the line is highlighted. - Print: When you want to print a region of text, the first line of the region must already have been marked with the M command. Then, use the cursor keys to place the last line of the region at the bottom of the screen. When you press P, you will be able to set up the printer automatically with BOYAN's printer interface (see section 4.5.4), and then the region will be printed. 4.7.2: BOYAN Command Capabilities 68 ________________________________________________________________________ - Quick-learn region: The Q command lets expert BOYAN users bypass the normal interactive Script Learn Mode. To use this command, mark the top line of the region to learn, and then scroll so that the last line of the region is at the bottom of the screen. BOYAN will learn a script file covering the entire region, suppressing the normal Waitfor/Response prompts. Since this script may well require fine- tuning, BOYAN offers you the chance to edit the script immediately after learning it. - Script Learn Mode: described below. - Word process (edit) region: Like the F command, this command writes the region between the mark and the current bottom line of the screen to a disk file. However, the W command then immediately invokes your text editor on that file. This is a handy way to quote from a message, for example. Note that if the buffer should become full, the oldest text in the buffer will be overwritten by new text as it flows in. 4.7.3 Script Learn Facility The most common use of script files is probably for automatic logging-on to a system. Rather than making you mechanically enter your name and password each time you connect, the computer should be able to do this for you. BOYAN script files are wonderful for automating such communication chores--typing out answers to prompts which are the same every time. Best yet, you do not even have to learn BOYAN's Script Language in order to write custom scripts. BOYAN's "Script Learn" facility writes them for you. During a communication session the scroll-back buffer always keeps track of which portions of the buffered text were received from the remote system, and which portions were typed by you. It also remembers when you executed certain commands, such as clearing the screen, opening a disk log file, or hanging up. Later, even after you have logged off, BOYAN can convert any region of the scroll-back buffer into an automated script file. All you have to do is find the location in the buffer where you want learning to start, and press S. 4.7.3.1 Example: Auto-Logon Scripts The simple procedure outlined below demonstrates how to make BOYAN "learn" a script to automate logging onto a typical system. 1. Dial the system and log on as usual. Enter your name, password, etc. at all the appropriate prompts. When you reach the point at which you want the automatic logon to stop--typically the 4.7.3.1: BOYAN Command Capabilities 69 ________________________________________________________________________ system's "Main Menu"--press <UpArrow> to enter BOYAN's Scroll- Back buffer. 2. The next step is to scroll back to the first line in the buffer to be learned. That line should be placed at the bottom of the screen. In the case of a logon script, you can do this by simply pressing <Home>, which scrolls back to the beginning of your session. 3. Press S to start Script Learning. You will be prompted to enter a name for your script file. Type a name of 1-8 letters and press <Enter>. (You do not need to add the ".BSC" script filename suffix; BOYAN does that automatically.) If the file you specify already exists, BOYAN asks you to choose whether to [A]dd to the current script, or build a [N]ew script (overwriting the old one). 4. BOYAN will scroll to find the first system prompt to which you responded. That prompt will be highlighted on the screen and also displayed on the Status Line, where BOYAN displays the message "WaitFor:". All you have to do is press <Enter>. This confirms that you want the auto-logon script to wait for the prompt before continuing. (Note: if the prompt is very long, BOYAN only needs to know its last 25 characters. It is normal for the beginning of the prompt not to be highlighted.) 5. Next, the status line displays your response to the prompt, as shown in the Scroll-Back buffer. Your response is followed by the "{" character, which symbolizes a Carriage Return. If the response shown is correct, just press <Enter>. 6. BOYAN scrolls ahead to find the next system prompt you answered. Again, confirm BOYAN's "WaitFor:" and "Response:" cues by pressing <Enter>. As you continue to press <Enter>, BOYAN automatically builds the logon script in your script file directory. 7. When you reach the end of the buffer, BOYAN reports "learning finished." (You may also finish by pressing <Esc> before reaching the end of the buffer, if the region to learn does not extend to the end of the buffer.) Press <Esc> to return to the communication screen. 8. Now that the auto-logon script has been written, you must follow one last step to make the logon completely automatic: put the logon script name in the system's dialing directory entry. Press <Alt-D><E> to edit the entry, press enough <Enter>'s to move to the "Script" column, and type the name of your newly-created script. Then press <PgDn> to complete the directory entry. 4.7.3.2: BOYAN Command Capabilities 70 ________________________________________________________________________ That's it! The next time you dial that system, the logon will proceed entirely automatically. 4.7.3.2 Password Security Feature BOYAN's Script Learn Mode includes logic to determine when you may have typed your password to the remote system. In such a case, it provides you with a default response consisting of not your actual password, but rather the macro %PW{ . This macro, when executed in a script file, sends your system password as specified in the Dialing Directory (plus <Enter>). Using %PW in a script instead of the literal text of your password has several advantages: - If you change your password, you do not need to edit your logon script file; - You can use the same script file with many systems, even if you use a different password on each; - You can share your script files without compromising the privacy of your passwords. 4.7.3.3 Details on Script Learning An auto-logon script file is just one example of the kinds of scripts BOYAN can "learn." The procedure described above works just as well for learning any part of any session. For example, if a system has a cumbersome signing-off process, you could make BOYAN learn an auto- logoff script. To invoke that script later, you would use BOYAN's <Alt-R> "Run script file" command, and type the script's name. (You could also assign a script file to a single keypress--see section 5.3.) A summary of the learning procedure is on Help Screen K, the Scroll-Back buffer help screen. BOYAN's Learn Facility is unique in allowing you to decide "after the fact" to go back and learn a script file. If your scroll-back buffer is large enough, you can even wait until after you have logged off before learning a script, saving on connect fees and long-distance rates. BOYAN's Learn mode is also unique in letting you "touch up" the script file as it is created, thus sparing the need for later trial-and-error editing. At the "WaitFor" and "Response" prompts, you have the chance to edit BOYAN's suggested values with the Line Editor. The "Response" prompt, in particular, gives you a great deal of flexibility: you can enter not just a string to be sent over the modem, but any BOYAN macro command. For example, to make a response of control-C, type ^C at the "Response" prompt, overwriting the default response. To make the script automatically send a modem break signal, append the \SB macro command after your actual (typed) response. 4.7.3.3: BOYAN Command Capabilities 71 ________________________________________________________________________ In addition to keeping track of the WaitFor/Response pairs, BOYAN's Scroll-back Buffer remembers when any of the following macros are used: \BB* (Beeps & Bells ON/OFF), \EC* (Echo keyboard ON/OFF), \HU (Hang Up), \LD* (Log to Disk ON/OFF), \PR* (Log to Printer ON/OFF), \RC (Reset text Color), \UF* (Usage File logging ON/OFF), and \ZS (Zap screen). These macros are copied, with comments, into a script as it as learned. You are given the chance to edit these macro commands at the "Macro:" prompt. If your system has 256K of memory or less, or if you have reserved a large amount of memory for BOYAN's DOS Shell (in Config Area <S>), then BOYAN's Scroll-Back buffer may not be very large. In this case, be especially careful to insure that the region to be learned does not scroll out of the top of the buffer. 4.7.4 <Alt-M> Enter Macro Manually After pressing <Alt-M> you will be prompted, "MACRO:". Whatever you enter will be instantly processed as a macro. For example, if you type the macro \RE50[-], then a line of fifty dashes will be sent over the modem. BOYAN remembers the macro you type so that the next time you select <Alt-M>, you can reuse or edit your previous macro. More than 300 macro commands and variables are available; see chapter 5 for details. 4.8 BOYAN's Host Mode BOYAN's main purpose is to make your computer act as a terminal, dialing out to connect with other "host" systems. However, using BOYAN's Host Mode, your computer can act as a simple host, accepting calls from other terminals. BOYAN allows you to maintain a database of up to 70 callers, each with their own password and user level. The available user levels and functions are: - User Level 0 (New User) - View file directories; view ZIP file contents; read messages; leave private comment to operator. - User Level 1 (Normal User) - Level 0 functions, plus: Enter messages; download and upload files in the Host directory. - User Level 2 (Sysop) - Level 1 functions, plus: Kill messages; download and upload files to any directory; Jump to DOS and run any program remotely; Shut down Host mode. 4.8.1: BOYAN Command Capabilities 72 ________________________________________________________________________ It is simple to modify the available functions at each user level, add more user levels, or even add new commands. Since BOYAN's Host Mode is implemented as a script file, every aspect of its operation can be customized for your needs. 4.8.1 Preliminaries To use BOYAN's Host, you must have a modem which meets the following basic conditions: 1. It can accurately report the "Carrier Detect" signal as described in section 2.3.2. 2. When your phone rings, it displays the "RING" message on the screen. 3. When you establish a connection at 1200 baud or greater, it displays the "CONNECT xxxx" message, where xxxx is the baud rate of the connection. Almost all Hayes-compatible modems will work with BOYAN's Host. The mechanics of BOYAN's Host Mode are contained in the HOST.BSC script file, located in your BOYAN script directory. The Host Mode also makes use of the HOST.BAM Action Module, which allows you to configure the host in Config Area <A>, and enables the host's "Local Test" feature. Finally, if you wish to run full-screen programs (like a word processor or database) remotely, you must install Marshall Dudley's DOORWAY.EXE program into your BOYAN directory. BOYAN's Host Mode can be used in any of three different types of con- nection: Modem, Direct, and Local Test. - A MODEM connection means that the Host waits for the phone to ring, tells the modem to answer, and hangs up the modem when the caller logs off. This is the normal mode of operation. - A DIRECT connection means that the Host does not require the phone to ring or a modem's carrier signal. If you have connected two computers with a "null modem" cable, BOYAN's Host in DIRECT mode provides a convenient way to transfer files between the two computers. - A LOCAL TEST connection actually causes the Host not to send any data over the serial port at all. When in LOCAL TEST mode, you can operate the Host mode locally--to test how it works without having to call in from another computer. 4.8.2: BOYAN Command Capabilities 73 ________________________________________________________________________ Local Test mode is selected with option J in Config Area <A>. When Local Test mode is OFF, option I in Config Area <A> toggles between a MODEM connection (YES) and a DIRECT connection (NO). Please refer back to section 3.10.3 for complete configuration instructions. 4.8.2 <Alt-I> Invoking Host Mode Press the <Alt-I> key to invoke the HOST script file. The message "Host Mode Invoked" will be recorded in the HOST.USE usage log. If you have selected a MODEM connection, then BOYAN will wait for the modem's RING message, answer the phone, and set the modem speed based on the "CONNECT xxxx" message. (Exception: BOYAN does not wait for the RING message if it detects that the modem is already online.) Otherwise, if you have selected a DIRECT or LOCAL TEST connection, BOYAN will immediately act as a host, prompting for a name and password. 4.8.3 Using the Host BOYAN's Host Mode offers much the same feel as a Bulletin Board System. In the description of the Host session which follows, we'll suppose that someone named Barney has called your system, and you are the Sysop watching on the Host Mode end. Note that whenever Barney is asked to respond to a Host Mode prompt, you (the Sysop) may "assist Barney" by typing his answer for him. "Welcome to BOYAN 5 Host!" greets Barney when he connects. As prompted, he enters his full name and password. If this is Barney's first call to the host, he will be asked to choose a password. BOYAN then creates a new entry in the Host Mode database which looks like this: Barney Rubble;bambam;0; first called on 09/22/91 at 10:45 The "0" represents the User Level of 0 which is automatically assigned to all new users. To raise Barney's User Level to 1 (regular user) or 2 (Sysop), you should select the <L> option from the local Sysop menu. Alternatively, you may edit the Host user database directly in Config Area <A>. Having successfully logged Barney onto the system, BOYAN searches the Host Messages directory for a file named WELCOME.MSG (use a text editor to create this file). If the file is found, BOYAN displays it for Barney. As the message is being displayed, he may press <Ctrl-S> to pause the output and <Ctrl-Q> to resume it. Now, Barney reaches the Boyan-Host Command Menu, which offers many commands. A description of each of the commands follows. Next to each command is the minimum user level (0, 1, or 2) required to use that command. 4.8.4: BOYAN Command Capabilities 74 ________________________________________________________________________ 4.8.4 Host User Command Menu - Comment to operator (0): Allows Barney to enter a private message to you. The comments are all stored in a single file named COMMENTS.HOS in the Host Message directory. The HOST.USE file records that Barney left a comment. You may view the comments by selecting option <W> on the Sysop menu. - Download a file (1): Transfers a file from your system to Barney's. First, Barney is prompted to specify the protocol he wishes to use for the file transfer. Then, he is asked for the name of the file to download. This is usually a single filename, but it may include wildcards (i.e., *.ZIP) if Barney has selected a batch file protocol such as Zmodem. If Barney has user level 2, he may give a full path specifier as part of the name; at user level 1, the file(s) must exist in the Host Files directory. Barney is told to begin downloading; from your end it looks like an upload to Barney. The file transfer is recorded as an upload in the HOST.USE log. - Enter a new message (1): Lets Barney type a message file that all callers can read. The message should be given a name of 1-8 characters; it will be saved under that name + a suffix of .MSG. Barney will be prompted to enter his message, line-by-line. The Host offers "word-wrap" so Barney does not need to press <Enter> at the end of each line. After finishing his message by pressing <Enter> twice, Barney may Abort, Continue, List, or Save his message. If he saves the message, that information will be recorded in the HOST.USE file. - File listing (0): Displays a DIR listing of the Host Files directory. - Goodbye (0): Logs Barney off from the system. The length of Barney's call is recorded in the HOST.USE file. The Host Mode automatically "cycles" to prepare for the next caller. Note: if Barney simply hangs up the modem without selecting G, BOYAN can usually detect it and cycle properly. Nevertheless, it is more reliable to log off with the G command. - Jump to DOS (2): Allows Barney to remotely take control of your computer's DOS. If you do not have Marshall Dudley's DOORWAY.EXE program installed in your BOYAN directory, then Barney will be able to execute only simple DOS programs such as TYPE, COPY, DELETE, PKUNZIP, and EDLIN. However, if you have installed DOORWAY.EXE, Barney can run any program at all on your system: spreadsheets, word processors, etc. Please see the DOORWAY documentation for full details. To return from DOS to BOYAN's Host, Barney must type the DOS command EXIT. The HOST.USE log notes that Barney jumped to DOS. 4.8.4: BOYAN Command Capabilities 75 ________________________________________________________________________ - Kill a message (2): Allows Barney to delete any of the *.MSG files in the Host Message directory. - List message titles (0): Displays a listing of all *.MSG files in the Host Messages directory. (The HOST.BSC script does this by first using DOS to create a temporary file with the DIR listing, and then ASCII-uploading this temporary file. This method allows Barney to use the <Ctrl-S> key to pause the display, and <Ctrl-Q> to resume it.) - New password (0): This allows Barney to change his password. He must type his previous password once and his new password twice to confirm the change. The HOST.USE log notes that Barney changed his password. - Operator page (0): If it is not between midnight and 8:00 am, this command sounds an alarm on your computer. Press G to Gossip with Barney or <space> to give him a polite message that you are not available to chat. To return Barney to the Host Command Menu after chatting, type <Tab>, R. - Read a message (0): Prompts Barney to type the name of the .MSG file to read, and displays it for him. - Shut down host (2): Allows Barney to abort the HOST script remotely. Not only does this command log Barney out, but no further calls will be answered by the host. - Upload a file (1): Transfers a file from Barney's system to yours. The upload procedure is exactly analagous to the download procedure described above. Barney must have user level 2 in order to upload into a directory other than the Host Files directory. In no case may Barney upload over a file which already exists; to accomplish that, he must first Jump to DOS and manually delete the file. - X = Expert mode toggle (0): This allows Barney to condense the Boyan-Host command menu into a 1-line list of the available command letters, or expand it back to its normal state. - Zip file contents (0): Prompts Barney for the name of a .ZIP file in the Host Files directory; then uses PKUNZIP to display its contents. 4.8.5 Local Sysop Menu At any time during Host Mode operation, you may press <Tab> to invoke the Sysop Menu. This menu changes depending on whether the Host Mode is offline (waiting for the phone to ring) or online (Barney is logged on). While offline, the Host offers a Sysop Menu with the following options: 4.8.5: BOYAN Command Capabilities 76 ________________________________________________________________________ - <Esc>: Aborts the Host Mode! To resume the Host Mode from the Sysop Menu, use the R command instead. - File Manager: invokes the File Manager (see section 4.6.1) in the Host Message directory. - Host Configuration: enters Config Area <A>, where you can edit the Host User database, the number of rings required before the Host answers the phone, etc. (see section 3.10.3). - Jump to DOS: type EXIT to return to the Host. - Parameters: lets you view/modify the current modem parameters as described in section 4.2.3. - Resume Host Mode: escapes from the Sysop Menu back to normal Host Mode operation. - Scroll-back Buffer: invokes the buffer (see section 4.7.2). This is useful for looking over what the last caller did while online. - Toggle 43/50-line mode: If you have an EGA monitor, this command will switch your screen display between 25 lines and 43 lines. On a VGA monitor, the display will switch between 25 and 50 lines. - View HOST.USE usage log: displays the Host usage log file, detailing all Host Mode callers and their activities. - W = View COMMENTS.HOS comments file: displays the file of user comments to the operator. If a caller (say, Barney) is online when you press <Tab> to invoke the Sysop Menu, the menu will include the following additional commands: - Cycle Host: immediately hangs up on Barney and prepares the Host for the next caller. - Gossip with Barney: this option switches you into BOYAN's split- screen "Gossip" Mode and advises Barney to do the same. To return Barney to the Host Command Menu, type <Tab>, R. - L = Change Barney's User Level: press L, then select a new user level for Barney (0, 1, or 2). Barney's entry in the Host user database will instantly be updated to reflect Barney's new status. 4.8.6: BOYAN Command Capabilities 77 ________________________________________________________________________ 4.8.6 Customizing HOST.BSC Using BOYAN's Macro Programming Language, you can customize every aspect of BOYAN's Host Mode in the HOST.BSC script file. The following chart indicates how the script allocates BOYAN's User Variables: Set automatically by the HOST Action Module: %V2 = number of phone rings before answering %V3 = MODEM if connection is over a modem, DIRECT if connection is direct, LOCAL if we're doing a local host mode test. %V4 = The host messages directory (where messages are saved) %V5 = The host files directory (for user level 1 files) Other variables used by the script: %VC = commands available at this user level %VE = extra info about caller %VF = caller's first name %VI = caller's ID number (41..110) %VL = caller's user Level (0=new user, 1=regular, 2=sysop) %VN = caller's Name %VO = current host status, "in-use" or "waiting" %VP = caller's Password %VR = previous Action Module %VU = previous usage file name %VX = "Expert" user mode (ON or OFF) The script uses the \TV and \TM macro commands to edit the Host user database, which is stored as the Host Mode's "terminal keyset." You may also access and modify the database directly in Config Area <A>, as described in section 3.10.3. Here are some examples of how you might customize HOST.BSC: - To enable the host to provide a new external protocol on its protocol menu: following the example of the other external protocols such as Zmodem and Kermit, you must add two lines to the SetProtocol block of the HOST.BSC script. - To change the commands available at each user level: look at the first few lines of the MENU block. Depending on the user level (%VL), the variable %VC is set to hold a list of available command letters. Simply add or delete letters from within the appropriate \SVC[..] command to change the power of that user level. 4.9: BOYAN Command Capabilities 78 ________________________________________________________________________ 4.9 BOYAN's Backspace Editor Often, when you are typing in a line of a message, you notice an error you made at the beginning of the line. Correcting this with other communication programs involves backspacing all the way past the error, then retyping the entire line the way it was. Although you may still use this method if you like, BOYAN provides a much easier way. The following commands are effective whenever you are in terminal mode: 4.9.1 <Backspace> Erase Previous Character As usual, the <backspace> key erases the previous character on the screen. BOYAN automatically stores this character in memory. 4.9.2 <LeftArrow> Forget Previous Character Pressing the <LeftArrow> key while in terminal mode also sends a backspace signal over the modem. However, BOYAN does not store the character in memory. 4.9.3 <Ctrl-Backspace> Erase Previous Word To erase the previous word typed on the current line, at any time, press <Ctrl-Backspace>. BOYAN simply sends backspace signals over the modem until it reaches a space. The erased word is stored in BOYAN's memory. 4.9.4 <Ctrl-LeftArrow> Forget Previous Word The <Ctrl-LeftArrow> command also sends backspace characters to erase the previous word. However, BOYAN does not store the word in memory. 4.9.5 <RightArrow> Un-erase Character Press <RightArrow> to recall the most recent character stored in BOYAN's backspace memory. In other words, the <RightArrow> key undoes the effect of the <Backspace> or <Ctrl-Backspace> commands. 4.9.6 <Ctrl-RightArrow> Un-erase Word Press <Ctrl-RightArrow> to recall all characters in BOYAN's backspace memory up to a space. This command also undoes the effect of the <BackSpace> and <Ctrl-Backspace> commands. 4.9.7 Using the Backspace Editor Suppose you type the following line to the modem: I have used the BOYA Communications program _ 4.9.7: BOYAN Command Capabilities 79 ________________________________________________________________________ (Your cursor is where the _ is.) You then realize that you left out the N in BOYAN. To fix it with the Backspace Editor, use any combination of the <Backspace> and <Ctrl-Backspace> commands to position the cursor on the space where you want the N . Press N. The line should read: I have used the BOYAN_ Now use the <RightArrow> and <Ctrl-RightArrow> commands to recall the erased part of the line. Suppose you wish to change the phrase "I have used" to "I use". Use the <Ctrl-Backspace> and <Backspace> commands to position the cursor to the right of the "d" in "used". Then press the <LeftArrow> key to backspace over the "d". The <LeftArrow> key backspaces without remembering the erased character. Press <Ctrl-Backspace> to back past the word "use", then press <Ctrl-LeftArrow> to delete the word "have". Finally, use the <RightArrow> and <Ctrl-RightArrow> commands to pull back the rest of the line: I use the BOYAN Communications program _ Once you get used to the Backspace Editor, you will find that you never post messages with typos again! Chapter 5 BOYAN Power--Macros and Script Files 5.1 Overview A macro is a sequence of commands which instructs BOYAN to perform some action. Beneath the "surface" of BOYAN which you normally see, macros are responsible for a variety of tasks--for instance, dialing the modem, handling your keyboard commands, and maintaining the activity log. Because all these macros are user-programmable, you have a great deal of power in determining what BOYAN does, and when and how it does it. BOYAN's Macro Programming Language is described in section 5.2. Many useful sample macros are presented in section 5.3. To automate even the most complex communication tasks, BOYAN allows you to link many macros together into text files called "scripts." Although BOYAN can create simple scripts automatically with the Script Learn facility (section 4.7.3), you can write much more powerful scripts. A script file could take control of your computer at a pre-assigned time, dial into a database, perform a search, and print the results--all with nobody at the keyboard. BOYAN's Host Mode is written completely as a script file. Still another application for script files might be to create a customized front-end menu interface for all of BOYAN's commands. BOYAN scripts are explained in section 5.5. 5.2 The Macro Programming Language Most macro/script commands consist of a backslash plus two characters; for example, \zs is the command to "zap" (clear) the screen. Many commands also require further information enclosed in square brackets; for example, \di[730-2917] is the command to dial the specified phone number. A macro is a sequence of one or more commands, all strung together on a line of text. Thus the macro \zs \di[730-2917] would instruct BOYAN to first clear the screen, and then dial the modem. Spaces may be placed between commands to make the macro easier to read. 5.2: BOYAN Power--Macros and Script Files 81 ________________________________________________________________________ The Macro Programming Language also provides approximately 100 variables which can be included in any command. Variables are specified by a percent sign plus two characters; for example, %XP represents the current X-position of the cursor. Wherever a BOYAN variable is found in a macro, it is replaced by its current value. (A variable may also be specified with an @-sign, e.g., @XP instead of %XP. The technical difference between % and @ is explained in section 5.5.6.2.) The next several sections explain the many variables and commands you can use to automate BOYAN. The commands and variables have been divided into categories such as String Output, Dialing, File Transfers, User Variables, and Script-specific commands. Note that there is also an alphabetical summary of all macro commands and variables at the end of this chapter. 5.2.1 String Output Any macro can include a string of text like "password". Such a string is sent directly over the modem. Eight characters--the caret, quotation mark, backquote, tilde, left curly brace, percent sign, at-sign, and backslash--have special meanings and are not sent directly over the modem unless they are preceded by a quotation mark. The special meanings of these characters are described in section 3.9.1. The following example demonstrates some basic commands: ATZ{~```\$```WELCOME CLASS OF "`99{ The example sends ATZ <Enter> to the modem, and then pauses for one-half second (~). The backquotes are for spacing and the macro processor ignores them. The \$ command causes Shortcut macro #114 to be processed. Finally, the phrase WELCOME CLASS OF `99 is sent to the modem, where the quotation mark signifies that the character that follows, the backquote, should be sent over the modem, not ignored like the other backquotes. 5.2.2 How to Read the Macro Definitions In the command format descriptions, the following conventions are used: c represents a single character, like Y x, y, or z represents an integer number, like 12. Numbers may be specified in hexadecimal if they are preceded by a $ sign, like $1B. filename represents a full filename specifier, such as FOO.ZIP or C:\MODEM\FILES\BOYAN.DOC. 5.2.2: BOYAN Power--Macros and Script Files 82 ________________________________________________________________________ string represents a string of characters not to be processed as a macro, like WELCOME! macro represents an executable macro, like \DI[730-2917] 5.2.2.1 Conditional Macro Syntax Conditional macro commands allow your macros to make decisions. With each conditional command, you enclose a macro in brackets which is to be executed only if the condition is met. For example, the \CA+[..] conditional macro tests whether there is a carrier signal. The macro: \CA+[\ST[You are online.]] displays the Status message "You are online" only if there is a carrier. If there is no carrier, then the macro has no effect. If-then-else decisions may be programmed by placing the special string |ELSE inside the enclosed macro. You may abbreviate the |ELSE by a single vertical bar |. The part of the macro beyond the |ELSE string is executed only if the condition was NOT met. For example, the macro: \CA+[\ST[You are online.] |ELSE \ST[You are offline.]] displays "You are online" if the carrier signal is detected, or "You are offline" if no carrier is present. The identical effect can be achieved using the complementary \CA-[..] macro: \CA-[\ST[You are offline.] |ELSE \ST[You are online.]] * * * * Each macro command and variable below is presented with its format on the left, an example on the right, and a mnemonic and description following. 5.2.3 Modem Commands ^c ^[ Sends the specified control character; e.g., ^X sends a control-X; ^[ sends the <Escape> character. Note that ^M, which sends a <Return>, can also be represented as { in a BOYAN macro. \CA+[macro] \CA+[\DM[You have connected!]|\DM[No connection.]] \CA-[macro] \CA-[ATS0=0{] CArrier? The \CA+ command processes the enclosed macro only if BOYAN detects carrier, that is, if the modem is currently connected. The \CA- command processes its macro only if BOYAN does not detect carrier. 5.2.3: BOYAN Power--Macros and Script Files 83 ________________________________________________________________________ \CH[x] \CH[127] CHaracter. Sends the ASCII character with code x (0..255) over the modem. For example, ASCII 127 represents the "Del" key on many terminals, so \CH[127] would simulate pressing "Del." ASCII character 27 is "Escape", so \CH[27] has the same effect as ^[. \CM Change Modem parameters. This macro calls up a menu, from which the user can change the modem device, speed, or parity. \CD[x] \CD[2] %MD %MA %MN 2 3E8 4 Change Device (serial port). The \CD macro changes the current modem device to port 1, 2, 3, or 4, and resets that port. The %MD variable holds the number of the current Modem Device (1..4). Variable %MA holds the memory address of the port in hexadecimal (without the $ sign), and %MN holds the IRQ Interrupt line used by the port (2, 3, 4, or 5). \CS[x] \CS[1] %MS %MM 1200 Change Speed. This changes the current modem speed setting to 300, 1200, 2400, 4800, 9600, 19200, or 38400 baud depending on whether x is 3, 1, 2, 4, 9, 0, or 8. You may also use the full number if you wish, like \CS[19200]. %MS holds the current baud rate, and %MM holds the Maximum Modem speed as configured in Config Area <S>. \CP[c] \CP[E] %MP E Change Parity. This changes the current modem parity setting to None, Even, or Odd depending on whether c is N, E, or O. You may use the full word if you wish, like \CP[Even]. %MP stores the current Modem Parity--N, E, or O (not the full word). \DD+ \DD- \DD* Drop DTR. \DD+ causes the DTR signal to be Dropped upon changing ports or exiting BOYAN, in effect hanging up the modem. \DD- makes BOYAN maintain the DTR signal when exiting. \DD* toggles between the two. \DT+ \DT- \DT* \DT-~~\DT+ DTR. Use \DT+ to turn the Data Terminal Ready signal ON, \DT- to turn DTR OFF, or \DT* to toggle its state. Turning DTR off for one second usually makes the modem hang up. \HU Hang Up. This hangs up the modem by running BOYAN macro #4. \PL Purge Line. This purges the data line of all incoming characters; i.e., ignore all incoming characters until the receive buffer is empty. 5.2.4: BOYAN Power--Macros and Script Files 84 ________________________________________________________________________ \SB Send Break. This sends a modem break signal. 5.2.4 Terminal Characteristics \AM[] \AM[c] \AM[G] Action Module. If the space between the brackets is empty, BOYAN provides a menu from which you can select a new Action Module. If you include a character between the brackets, BOYAN attempts to load the Action Module corresponding to that character: [1]=VT-100, [G]=GOSSIP, etc. %AM G Action Module. The letter or digit corresponding to the current BOYAN Action Module in use. %AN GOSSIP Action module Name. The full name of the current BOYAN Action Module. %AP 1 Action module (Previous). The letter or digit corresponding to the previous BOYAN Action Module in use; that is, the module which was in use before the current one was selected. For example, the macro \AM[%AP] would instruct BOYAN to switch back to the previous action module. \B8+ \B8- \B8* %B8 Bit 8. The \B8 command controls whether or not BOYAN recognizes the eighth (high) bit of incoming characters. \B8+ makes BOYAN recognize the eighth bit, allowing IBM graphics characters to be seen. \B8- causes BOYAN to strip the eighth bit, converting IBM graphics characters to their regular 7-bit ASCII equivalents. \B8* toggles back and forth between the two states. The %B8 variable equals "ON" when the eighth bit is allowed, or "OFF" when the eighth bit is stripped. \BD+ \BD- \BD* %BD Backspace/Del swap. Certain terminal emulation BAMs such as VT-100 and IBM-3101 offer an option to swap the Backspace and Del keys. When in such a BAM, you may use the \BD+ macro to swap the keys, \BD- to "unswap" the keys, \BD* to toggle between \BD+ and \BD-, and the %BD variable to reflect whether BS and Del are currently swapped ("ON") or normal ("OFF"). \BU+ \BU- \BU* %BU BUffering. You must have the National Semiconductor 16550AN UART chip to use this command. The 16550AN provides FIFO buffering of received modem text, which makes high-speed downloads reliable even under a multitasking or network environment. The \BU+ command initializes the 5.2.4: BOYAN Power--Macros and Script Files 85 ________________________________________________________________________ FIFO buffer to its maximum size of 14 bytes, and modifies BOYAN's interrupt processing routine appropriately. \BU- disables the buffer, and \BU* toggles. Technical note: when you shell to DOS or exit BOYAN, FIFO buffering is restored to the state it was in upon entering BOYAN. \CT+ \CT- \CT* CTS/RTS. Use \CT+ to turn CTS/RTS hardware flow control ON, \CT- to turn CTS/RTS flow control OFF, and \CT* to toggle between the two settings. \EC+ \EC- \EC* %EC ECho. \EC+ turns local echo ON, \EC- turns local echo OFF, and \EC* toggles back and forth between the two. The %EC variable can always be used to determine the current state of echo mode: %EC equals "ON" or "OFF". \LF+ \LF- \LF* %LF Line Feeds. \LF+ turns add line feeds mode ON, \LF- turns line feeds OFF, and \LF* toggles between the two. %LF maintains the current state of the toggle, "ON" or "OFF". \TT+ \TT- \TT* %TT Translation Table. \TT+ turns the table ON; \TT- turns it OFF; \TT* toggles it. The %TT variable reflects whether the table is "ON" or "OFF". \XX+ \XX- \XX* Xon/Xoff. Use \XX+ to turn Xon/Xoff software flow control ON, \XX- to turn Xon/Xoff control OFF, and \XX* to toggle between the two settings. 5.2.5 Backspace Buffer \BC Back destructively over Character. This command is identical to sending a backspace (^H), except the deleted character is not added to BOYAN's backspace buffer. \BW+ \BW- Back over Word. This sends backspaces until a space is reached. \BW+ saves the erased word in the backspace buffer; \BW- does not. \FC Forward Character. This sends the most recent character stored in the backspace buffer. \FW Forward Word. This sends characters from the backspace buffer until a space is reached. 5.2.6: BOYAN Power--Macros and Script Files 86 ________________________________________________________________________ 5.2.6 Timing ~ (tilde) BOYAN pauses for approximately 0.5 seconds whenever the tilde character is found in a macro. For long pauses, \PA[x] is a better alternative. %HR %MI %SE 18 09 59 HouR, MInute, SEcond. These variables hold the current hour, minute, and second, respectively. Each is exactly two digits long. The hour is given in 24-hour notation: i.e., at six o'clock PM, %HR equals 18; at midnight, %HR equals 00. %MO %DA %YR 09 03 92 MOnth, DAy, YeaR. Each of these variables is exactly two digits long. \PA[x] \PA[20] PAuse. This makes BOYAN pause for x (1..32767) seconds. See also the \AL macro command, which sounds an alarm for a specified number of seconds (section 5.2.10). \PU[##:##] \PU[2:30] Pause Until. Make BOYAN pause until the specified time. The above example would make BOYAN wait until 2:30 AM before continuing. Use 24- hour notation to specify times after noon; e.g., \PU[14:30] to pause until 2:30 PM. Note that midnight = 0:00. \SL[x] \SL[0] Set Line pacing to x (0..255) milliseconds. This is the amount of time BOYAN will pause after sending a Carriage Return in a macro or ASCII upload, in addition to the character pacing time. \SP[x] \SP[10] Set Pacing. This sets character pacing to x (0..255) milliseconds, the amount of time BOYAN will pause between sending each character in a macro or ASCII upload. \UT##:##[macro] \UT`20:00[\DM[%HR:%MI:%SE]] Until Time. Until the specified time (24-hour format), this repeatedly executes the enclosed macro. The above example would display a running clock on the screen until 20:00 (8:00 PM). 5.2.7 Handshaking \IF+string[macro] \IF+End of messages[\GB[LogOff]] \IF-string[macro] \IF-File not found[\DLk[twiddle.arc]] If Found? The \IF+ command processes the enclosed macro only if the specified string is found on the current screen line or the line immediately above the cursor. The \IF- command processes its macro only if the string is not on the current line or line above. The matching is 5.2.7: BOYAN Power--Macros and Script Files 87 ________________________________________________________________________ not case-sensitive. Once a given string on the screen is matched, it is highlighted and will not be matched again. See the related \WF and \UN commands. \IW+[macro] \IW+[\DM[Log-on successful!]] \IW-[macro] \IW-[\DM[Log-on interrupted.]\GB[quit]] If Waitfor successful? The \IW+ command processes the enclosed macro only If the last WaitFor, UNtil, or IF command was successful. The \IW- command processes the enclosed macro only if the last such command timed out before successfully making a match. \TO[x] \TO[40] TimeOut. Set the handshake timeout to x (0..255) seconds. This is the amount of time BOYAN waits before "giving up" trying to match a \WF or \WL command. If x is 255, then it means "indefinitely": \TO[255] sets an indefinite timeout, and BOYAN will never give up waiting for a match! \UNstring[macro] \UN`End of file[^K] UNtil. This repeatedly executes the macro enclosed in the brackets until the specified string arrives from the modem. The above example sends a continuous stream of control-K characters until BOYAN sees the "End of file" message. \WF[] \WF[] \WF[string] \WF[Enter your name:]John Johnson{ Wait For the specified string to arrive from the modem. If 30 seconds (or whatever value you configure or set with the \TO command) elapses before the string appears, the macro times out and will continue to the next command. The string is not case-sensitive, so NAME will match NaMe . If the brackets are empty, BOYAN will simply wait for any character. While BOYAN is waiting, if you press <space>, BOYAN will assume the matching was unsuccessful and continue to the next command. (Pressing <Esc> always aborts the entire macro/script.) You can use the \IW command to test for the success of the waitfor (section 5.2.7). See also the \UN (until) and \IF (if found) commands. \WL \WL Wait for a new Line (carriage return) from the modem. \WP[x] \WP[2]{ Wait for Pause. This command instructs BOYAN to Wait for a Pause of x seconds in the remote system's input. Suppose you execute the command \WP[2]. As long as input continues to flow in from the modem, the macro will simply wait. However, when there is a pause in the flow of input--in this case, two seconds during which nothing new arrives from the modem--the \WP[2] command will finish, and the macro processor will continue on to the next command. In effect, \WP[2] makes BOYAN wait for the next prompt for input! See the TCOMM.BSC script for details. 5.2.8: BOYAN Power--Macros and Script Files 88 ________________________________________________________________________ 5.2.8 Dialing \AD+ \AD- \AD* Auto-Detect. Use \AD+ to turn auto-detection of the modem connect speed ON, \AD- to turn Auto-Detection OFF, and \AD* to toggle between the two. This feature is explained in section 3.8. \CC+ \CC- \CC* Carrier Checking. \CC+ enables BOYAN's carrier checking before dialing. With carrier checking enabled, BOYAN will prompt you to verify that it is "OK to dial despite carrier" if you try to dial while already on- line. \CC- disables carrier checking; \CC* toggles. \CO[x] \CO[60] COnnect timeout. Set the COnnect wait time to x seconds (0..99). After dialing with <Alt-D>, BOYAN will assume that no connection has been made if the modem fails to respond within this amount of time. \DI[] \DI[] \DI[x] \DI[12] \DI[string] \DI[Compuserve] \DI[###-####] \DI[381-6441] DIal. If the brackets are empty, \DI[] simply enters the dialing directory. If a number from 1-200 is enclosed, this command dials the system with the specified dialing directory code; if you make a connection, the appropriate automatic logon script will also be run (see section 5.5.2). If a string is enclosed, BOYAN will search your dialing directory for an entry whose name contains that string, and dial the first such entry it finds. (This may be preferable to giving the precise code number, since the code may change if you sort the directory.) Finally, if the string does not match any directory entry name, BOYAN attempts to manually dial the enclosed string. %F: C:\BOYAN\FON\ Fon path. This variable stores the name of the path in which BOYAN expects to find all its FON directories. To reconfigure this path, see section 3.6. \FD[filename] \FD[CHICAGO.FON] %FD CHICAGO.FON Fon Directory. The \FD macro command loads the specified new Fon Directory. The filename suffix of .FON is optional. If the file you specify is not a valid BOYAN directory, the previous .FON directory will be reloaded. The name of the current FON directory is always stored in the %FD variable. 5.2.8: BOYAN Power--Macros and Script Files 89 ________________________________________________________________________ \IS+x,y,..,z[macro] \IS+1,6,114,0,3,30[password1|password2] \IS-x,y,..,z[macro] \IS-0[\DM[Phone number = %SF.]] Is System? The \IS+ command processes the enclosed macro only If the directory code of the System you last dialed is on the list of numbers. The \IS- command processes its macro when the last-dialed system is not on the code list. The codes run from 1-200 for dialing directory entries, and 0 for manual dialing. This command is convenient when, for example, you use different passwords on otherwise-identical systems, and need to select a password based on which system you connected to. %PW ibm-pc %S# 12 %SF 1-301-854-3076 %SN BOYAN Support BBS %SS PCBOARD %SL 0:15:30 System information. These six variables contain information about the system which is currently online. If you are online with a system dialed from the dialing directory: %PW equals its password; %S# equals its code number (1-200); %SF equals its phone number; %SN equals its Name; %SS equals the name of its logon script file (without the .BSC suffix); and %SL is the total elapsed time since the connection was made. These values can be used in Auto-macros #6 and #7, for example, to update the BOYAN.USE activity log. When you are offline, %PW equals the default value set in Config Area <S>; %S# equals 0, the %SL clock keeps running, and the other variables are blank. 5.2.9 Queue Redialing \QA[x] \QA[12] \QA[###-####] \QA[381-6441] \QA[string] \QA[Boyan Support] \QA+[string] \QA+[Boyan Support] Queue Add. If a number from 1-200 is enclosed, this command adds the system with the specified dialing directory code to the redialing queue. Otherwise, BOYAN searches the dialing directory for an entry whose name contains string, and adds that entry to the Queue. If a + is placed before the left bracket, then all matching entries will be added to the queue; with no +, only the first matching entry is added. If the string in brackets is not an entry name but a phone number, then BOYAN will simply add that number to the queue. \QA-[x] \QA-[12] \QA-[string] \QA-[%SN] Queue Subtract. If a number from 1-200 is enclosed, this command deletes the entry with that code number from the redialing queue. If a string is enclosed, then all queue entries whose names are "close enough" to that string are removed from the queue. To BOYAN, a queue name is "close enough" to the specified string if that string, not 5.2.9: BOYAN Power--Macros and Script Files 90 ________________________________________________________________________ including its last character, is contained as a substring of the queue name. For example, the command \QA-[BOYAN Support Line 2] will delete queue entries named BOYAN Support Line 1 and BOYAN Support Line 3 as well as BOYAN Support Line 2. If you insert the command \QA-[%SN] into Auto-macro #6, then after connecting to a system, all other systems whose names are "close enough" will automatically be deleted from the queue. \QC Queue Clear. Clear the queue of all entries. \QD Queue Dial. This makes BOYAN repeatedly dial the numbers in the queue until a connection is made. When BOYAN connects, it removes that number from the queue and rings the connect alarm. If the connected system has a logon script specified in its Dialing Directory entry, BOYAN stops ringing the alarm after the "Script Keyboard Timeout" has expired, and runs the script's LOGON block as described in section 5.5.2. If the queue is empty, this command does nothing. \QE Queue Enter. The \QE command causes BOYAN to enter the redialing queue and wait for user key commands. %QS \IE+%QS,0[\EX | \QD] Queue Size. The number of entries in the Queue (0..20). The example macro will exit BOYAN if the queue is empty, or begin queue redialing otherwise. \QU[##:##] \QU[6:15] Queue Until. This command is identical to the \QD command, except that redialing will stop at the specified time if no connection has been made yet. Use 24-hour notation, e.g., \QU[23] to redial until 11:00 pm. See section 5.3.2 for an example of how to use this command in an Auto- macro. 5.2.10 Screen & Sound \ALx[y] \AL1[5] \ALx[0] \AL3[0] \ALx[] \AL2[] ALarm. BOYAN provides three alarms: alarm #1 is a constant tone; alarm #2 is a two-tone "ringing"; and alarm #3 is a descending squawk. The pitch of the alarm is controlled by the alarm volume setting (below). The \ALx command rings alarm # x (1, 2, or 3). The number y (0..255) in brackets determines the length of the alarm in seconds. If y is 0, the alarm tone sounds just once, and stops. If the brackets are left empty, then the alarm will ring continuously until the user presses a key. 5.2.10: BOYAN Power--Macros and Script Files 91 ________________________________________________________________________ \AV[x] \AV[4] Alarm Volume. Change the alarm volume from 1 to 10, or silence all alarms with 0. \BB+ \BB- \BB* %BB \AV[0]\BB- Beeps & Bells. \BB+ turns Beeps & Bells mode ON; \BB- turns it OFF; and \BB* toggles between the two states. The %BB variable equals "ON" or "OFF" as appropriate. The example macro above can be used to completely silence all BOYAN sound effects. \DMC[x] \DMC[240] %DM 240 Display Message Color. Set the Display Message Color to x (1..255). This color will be used for messages displayed with subsequent \DM commands. Note that numbers greater than 128 are flashing; for example, select color 240 for flashing black on white. The %DM variable holds the Display Message color. \DM[string] \DM[You have connected!] \DMx,y[string] \DM40,10[Menu of Options] \DMy[string] \DM1[This message is in color %DM.] \DMx,[string] \DM30,[The time is now %HR:%MI.] Display Message. The \DM command is used to display a message on the screen. The string will be displayed at column x (1..80), line y (1..24). If either x or y is omitted before the string in brackets, then BOYAN substitutes default values. If x is omitted, BOYAN flushes the string to the right of the screen. If y is omitted, BOYAN uses the line above the current cursor position. In the examples above, "You have connected" is flushed right on the line above the cursor; "Menu of Options" is at column 40, row 10; "This message is in color ###" is flushed right on line 1; and "The time is now ##:##" is at column 30 on the line above the cursor. \DM can be used in conjunction with the \KV command to make user menus, for example (see section 5.2.14). \GL+ \GL- \GL* %GL Grab screen Lines (EGA/VGA monitors only). \GL+ loads the 8x8 ROM screen font, causing an EGA adapter to display 43 lines of text or a VGA adapter to display 50 lines of text. \GL- restores a 25-line screen. \GL* toggles between \GL+ and \GL-. The variable %GL always holds the current number of lines displayed (25, 43, or 50). \GX[x] \GX[40] Goto X-position. This moves the cursor horizontally to the specified column (1..80). \GY[y] \GY[20] Goto Y-position. This moves the cursor vertically to the specified row (1..24). 5.2.10: BOYAN Power--Macros and Script Files 92 ________________________________________________________________________ \KS \RS Keep Screen, Restore Screen. These commands are useful for making user-defined "pop-up" menus. \KS does several things: it saves a copy of the top 24 lines of the screen into memory; it saves the current cursor position; and it temporarily inhibits all I/O from the modem. After \KS, you could clear the screen (with \ZS) or display menu messages (with \DM). When you want to Restore the Screen contents and cursor position, use the \RS macro. Note: BOYAN restores the screen automatically, even without \RS, if either 1) you invoke a command which needs to save the screen (e.g., Dialing Directory or a file transfer), or 2) you abort the macro/script by pressing <Esc>. \MC[x] \MC[112] %MC 112 Menu Color. \MC[x] sets the Menu and help screen Color to x (1..127). The %MC variable holds the current Menu Color in use. \NC[x] \NC[7] %NC 7 Normal Color. \NC[x] sets the Normal text Color to x (1..127). The %NC variable holds the current Normal text Color in use. \RC Restore Color. This command Restores the default normal text Color. \RX[x] \RX[-10] Relative X-position. This moves the cursor horizontally by the specified number of spaces, backward (negative numbers) or forward (positive numbers). The cursor will not go beyond either end of the line. \RY[y] \RY[5] Relative Y-position. This moves the cursor vertically by the specified number of lines, up (negative numbers) or down (positive numbers). The cursor will not go beyond either end of the screen. \SN[string] \SN[%SN] System Name status. This displays the string on the right side of the status line, where the current System Name is normally displayed. \ST[string] \ST[Beeps & Bells are now %BB.] STatus. This displays the string on the left side of the status line. This sample macro displays the current status of the Beeps & Bells toggle. %XP %YP X-Position, Y-Position. These variables equal the current column (1..80) and row (1..24) of the cursor, respectively. 5.2.11: BOYAN Power--Macros and Script Files 93 ________________________________________________________________________ \ZS "Zaps" (clears) the Screen. 5.2.11 Session Logging & Printing \LD+ \LD- \LD* %LD %LN \LD*\ST[Logging to %LN is now %LD.] \LD+[filename] \LD+[C:\%MO-%DA-%YR.LOG] Log to Disk. \LD+ opens a log file. If no filename is specified, the default (or most recently-used log file) is used. Opening the log file runs Auto-macro #14, which inserts a header with the date and time in the file. While the log file is open, all text appearing on the communication screen is saved to the file. \LD- closes the open log file; \LD* toggles logging ON and OFF. The %LD variable maintains the status of the log file as "ON" or "OFF". %LN holds the full name of the last log file opened, or the default BOYAN.LOG if none has been opened yet. In the second example above, the date variables are used to open a log file with the date in the filename; for example, on November fourth, the filename used would be C:\11-04-91.LOG. \LM[string] \LM[== Connected to %SN ==] Log Message. This inserts a message in the log file if the file is open. If you include the example macro above in your Connect Auto-macro #6, then whenever you connect to a system while the log file is on, a line with that system's name will be added to the log. \PM[string] \PM[== Connected to system number %S# ==] Print Message. This command prints the specified string on your printer. You can use this command to set up printer initialization codes; for example, \PM[^X^[g] sends <Ctrl-X>,<Escape>,<g>. \PP[x] \PP[2] Printer Port. Select a new device (1, 2, 3, or 4) for all subsequent printing. \PR+ \PR- \PR* %PR PRinter. \PR+ turns printer log mode on. If used in a script file, printer logging starts immediately; otherwise, BOYAN's printer setup menu is displayed. All text appearing on the communication screen is printed until printer logging is turned off by \PR-. \PR* toggles printer logging; %PR equals "ON" or "OFF" as appropriate. \PS Print Screen. This is identical to keying <Shift-PrtSc> by hand. \SS %DN Save Screen to disk. This command saves the current screen to the BOYAN screen dump file (see section 3.6). The Dump file Name is stored in variable %DN. 5.2.11: BOYAN Power--Macros and Script Files 94 ________________________________________________________________________ \UF+ \UF- \UF* %UF \UF*\ST[Usage file now %UF.] \UF+[filename] %UN \UF+[LONGDIST.USE] Usage File. \UF+ and \UF- turn the BOYAN.USE usage file on and off, respectively. If a filename is specified after the \UF+ command, BOYAN will use that filename for the usage file. \UF* toggles the usage file, and the %UF variable holds its current status, "ON" or "OFF". %UN holds the full Name of the current Usage file. \UM[string] \UM[Current DOS directory = %C:] Usage Message. This command enters a line into the usage file. The date and time are automatically appended to the beginning of the line, in whatever format you specify (see section 3.6). To add a line to the usage file without the date/time prefix, use the command \AF%UN[..your msg here..] instead. If the Usage File is OFF, the \UM command has no effect. The example above would add a line to the end of the usage file showing the current DOS path. 5.2.12 DOS \AFfilename[string] \AF`LETTER.TXT[This file is dated %MO/%DA/%YR.] Append to text File. This very powerful command allows scripts to build custom text files. The string is appended to the end of the text file specified by filename. If that file does not exist, BOYAN creates it. The Host Mode script uses this command to create a message file as the message is being typed. See also the \GV command (for reading from a text file). %B: D:\BOYAN\ BOYAN path. This variable holds the BOYAN home directory's drive+path. %C: A:\ Current path. This variable holds the current disk directory's drive+path. \CF+ \CF- \CF* Check Free. \CF+ tells BOYAN to automatically check free disk space before each download and within the directory file manager. \CF- means you must manually press <Alt-F> in the download menu or F in the file manager to see remaining disk space. \CF* toggles. \DC[string] \DC[pkunzip -v boyan5a] \DC-[string] \DC-[dir >prn:] \DC+[string] \DC+[type %DN] DOS Command. BOYAN invokes the COMMAND.COM processor to execute [string] as a DOS command. If you use the \DC- command, BOYAN will continue immediately after the DOS command finishes. With \DC+, you will be prompted for a keypress before returning to BOYAN. The plain \DC command (with no minus) usually prompts for a keypress, but does not if there is a script file running. 5.2.12: BOYAN Power--Macros and Script Files 95 ________________________________________________________________________ %DR A DRive. This variable holds the currently-logged disk drive letter. %DS 125 DOS Shell space. This variable equals the amount of memory (in K) available for DOS Shells. If %DS equals 0, then the \JD and \DC commands cannot function. \FE+filename[macro] \FE+c:\files\twiddle.arc[\UL[twiddle.arc]] \FE-filename[macro] \FE-boyan5a.zip[\DC[pkzip boyan5a *.*]] File Exists? With the \FE+ command, the enclosed macro is processed only if the specified file exists on your disk. The \FE- command processes the enclosed macro only if the specified file does not already exist. \FM[filespec] \FM[c:\util\] \FMc[filespec] \FMU[] \FMstring[filespec] \FM`pkunzip -v[%D:*.ZIP] The File Manager. Within the brackets, specify the path and/or wildcard pattern of files to display, or leave the brackets empty to display all files in the current directory. There are also two ways to specify the File Manager "default command", which is the the command selected when you press <Enter> or double-click the mouse on a filename: 1. Between \FM and [filespec], include a single letter (any of C D E F I L M R S U V W). The File Manager command corresponding to that letter will become the default command. For example, \FMU[] invokes the File Manager in the current directory with Upload as the default command. 2. Between \FM and [filespec], include a DOS command two or more characters long. The File Manager default will then invoke that DOS command, giving it the name(s) of the selected file(s) as its argument. The "pkunzip -v" example above invokes the File Manager on all *.ZIP files in your Download directory; to view the contents of a .ZIP file, you would simply highlight that file and press <Enter>. \FS[c] \FS[%DR] Free Space. This displays a status message showing the number of bytes of free space on the specified disk drive. \JD \AT+[\JD] Jump to DOS. You must type EXIT <Enter> to return to BOYAN from DOS, so be sure this command is not processed when BOYAN is unattended. 5.2.12: BOYAN Power--Macros and Script Files 96 ________________________________________________________________________ %LC TYPE List Command. This variable holds the DOS command you have configured for viewing a file. For example, to view the BOYAN.USE file, you would run the \DC[%LC boyan.use] macro. \ND[string] \ND[b:\download] New Directory. This command selects a new default disk drive or path. %S: D:\BOYAN\SCRIPT\ Script path. This variable holds BOYAN's script file disk drive+path. %SC HOST.BSC SCript. This variable holds the name of the current script file running (or the last script file run, if none is active). %WC EDLIN Word processor Command. This variable holds the DOS command you have configured for editing a file. 5.2.13 File Transfers \AU+ \AU- \AU* %AU \AU* \ST[Auto-downloading is now %AU] AUto-downloading. \AU+ enables auto-downloading, \AU- disables, \AU* toggles between the two. %AU maintains the current state of the toggle, "ON" or "OFF". %D: C:\MODEM\DL\ %U: B:\ Download path, Upload path. These variables hold the name of the default download and upload directories, respectively. \DLc-[filename] \DLY-[c:\twiddle.zip] DownLoad. The \DL command offers three parameters, all of which are optional: 1. The first parameter is a letter or digit specifying the protocol to use for the download. The letter should be the same one used in the protocol menu, e.g., X=Xmodem, K=Kermit, etc. If you do not specify a protocol letter, the current default protocol will be used. Example: \DLY[] would invoke the Download Window with Ymodem as the default protocol selection. 2. The second parameter is an optional - minus sign. If you include the minus sign, then BOYAN will bypass its Download Window where you confirm the protocol, path, and filename; the download will begin immediately. Example: \DL-[] is used in Auto-macro #12 so that auto-downloads start without any keypresses on your part. 5.2.13: BOYAN Power--Macros and Script Files 97 ________________________________________________________________________ 3. The third parameter, enclosed in brackets, is the full name of the file to download. You may also specify a path only (but no filename), or leave the brackets empty. If you do not specify a filename, BOYAN will use its automatic filename-find feature to determine the name. (Some external protocols determine the filename automatically, in which case you may leave the brackets empty.) If you do not specify a filename and BOYAN cannot determine the name from the screen, BOYAN will name the file FILE####.BDL, where #### is the time of day when the download started. Examples: \DL-[twiddle.zip] will immediately begin downloading twiddle.zip into your default Download directory. \DL[%S:] will direct a download to your BOYAN script directory, prompting you for the filename. \DP[c] \DP[K] %DP K Default Protocol. This sets the default file transfer protocol. Put the first letter of the protocol (A, C, K, X, Y, Z, etc.) in the brackets. The current default protocol's letter is always stored in variable %DP. \IP+c[macro] \IP+K[\DLK[] | \DLX[]] \IP-c[macro] \IP-Z[\DM[Zmodem not installed.]] If Protocol available? The \IP+ command processes the enclosed macro only If the Protocol specified by the character c is available. The first example above performs a Kermit download if the Kermit protocol is available, or an Xmodem download otherwise. The \IP- command processes the enclosed macro only if the specified protocol is not available. \IT+[macro] \DLy[]\IT+[\DM[Ymodem download successful.]] \IT-[macro] \ULk[boyan5a.zip]\IT-[\DM[Upload failed.]] If Transfer successful? The \IT+ command processes the enclosed macro only If the most recent file Transfer completed successfully. The \IT- command processes its macro only if the last transfer was unsuccessful. %P: D:\BOYAN\EXTPROTS\ Protocol path. This variable holds the full name of the external protocol program path, configured in Configuration Area <D>. %T: C:\MODEM\DL\ %TF TWIDDLE.ARC Transfer path, Transfer Filename. The %T: variable stores the name of the most recent directory selected for a file transfer; %TF holds the name of the file most recently selected to be transferred. %TI Ymodem DL: ALLFILES.ARC 44,160 0:04:36 67.4% Transfer Information. After a file transfer, BOYAN builds an information string like the one above. The string consists of the protocol used, UL or DL, filename, file size, transfer duration, and 5.2.13: BOYAN Power--Macros and Script Files 98 ________________________________________________________________________ efficiency percentage. If the transfer is unsuccessful, the word (FAILED) follows the filename. This string can be included in the usage log, for example, as in Auto-macro #8 ("After a file transfer"). %UD UL UpLoad or DownLoad? This variable holds "UL" after an upload or "DL" after a download. \ULc-[filename] \UL-[c:\modem\files\twiddle.arc] UpLoad. The use of this command, UpLoad file, is analogous to the use of the \DL command. The protocol letter (c), minus sign, and filename parameters are all optional. If BOYAN cannot find the file for uploading, however, the upload will be aborted. \WW+ \WW- \WW* Word Wrap. \WW+ enables, \WW- disables, and \WW* toggles the automatic word wrap handling feature of message uploads. 5.2.14 User Variables %V0 %V1 ... %V9 %VA %VB ... %VZ These 36 user-definable variables, along with the following macro commands, give the macro language enormous power. A user variable can hold a string, a number, or a macro. \DVc[x] \II+;,%V0[\DV0[%II]] Deletes the leading x characters from the specified user Variable. For example, \SV0[Justin] \DV0[3] results in %V0 being set to "tin". The more complicated example above has the effect of deleting all characters up to the first semicolon in %V0. Combined with the \LV command, this command lets you pick out any substring from within a variable. (See HOST.BSC for many examples.) \GVc[filename] \RE[ \GV5[FOO.DOC] %V5{ \IV5+^Z[\EM] ] \GVc[] \GV5[] Get Variable from file. This command reads from an ASCII file into a user variable. Each successive call to \GV1[foo.txt] reads one more line from the specified file foo.txt. If you switch to another filename, e.g., \GV3[bar.doc], then foo.txt will be closed and the first line of bar.doc will be read. When you reach the end of the file, the user variable will contain the control-Z (EOF) marker. The example given above actually performs an ASCII upload of FOO.DOC: the macro repeatedly gets a line of text from FOO.DOC into %V5, then sends %V5 + <CR> over the modem, and checks to see if the ^Z marker was reached. It is a good idea to close any files opened this way by using the \GVc[] command. 5.2.14: BOYAN Power--Macros and Script Files 99 ________________________________________________________________________ \IVc+string[macro] \IV5+secret[Welcome! | Wrong password.] \IVc-string[macro] \IV0-[\DM[Input accepted.]] If Variable equals? The \IV command tests whether variable c equals string. \IVc+string[macro] is actually just a shortcut for \IE+%Vc,string[macro] , and similarly with \IVc-. The first example sends the "Welcome!" message if %V5 equals "secret", or the "Wrong password" message otherwise. The second example tests to see if %V0 equals the empty string--that is, if %V0 is empty. If not, then the "Input accepted" message is displayed. \KVc[string] \KV0[Your selection?] \KVcstring1[string2] \KV8%DR[New disk drive: ] \ND[%V8:] Keyboard Variable. This command lets you make BOYAN's macros and scripts interactive. BOYAN prompts you for keyboard input on the status line; what you type is stored in variable c. The string in brackets is the prompt; e.g., the first example above prompts the user with "Your selection?". You can specify a default response to the prompt by placing another string before the first left bracket. The second example above uses the %DR variable to make the default response the current drive letter; it then uses the \ND command to change to the new drive letter typed by the user. Note: when responding to a \KV prompt, you must press <Enter> after typing your response, unless the default response is one character long. If the default response is a single character, BOYAN expects a keyboard response of only one character, and does not require you to press <Enter>. In the second example above, since the current drive letter %DR is always just one character, the user does not have to press <Enter> after responding. \LVc[x] \SV1[%B:]\LV1[2] \LVc[] %LV \LV5[] \ST[Length of %V5 is %LV.] Length of Variable. This command allows your macros to perform basic string manipulation. If a numeric argument x is given, \LV sets the length of variable c to be exactly x (0..80) characters, padding with spaces if needed. In the first example above, %V1 is set to the BOYAN directory (e.g. "C:\BOYAN"), and then truncated down to two characters so %V1 = "C:". The %LV variable holds the new length of the variable. If no argument is enclosed in the brackets, then the length of the string is left unchanged. The second example above demonstrates how to find the length of a variable's contents without changing the variable. \RVc[y] Please type your name: \RV1[30] \RVc*[y] Please type your password: \RV2*[20] \RVc-[y] \WF[Time left:] \RVT-[20] \RVc+[y] \RVL+[70] Read Variable. This command is used to read input from the modem into user variable c. Up to y characters are accepted, and the entry must be terminated by a <Return>. Backspacing is allowed and handled properly. With the * parameter, BOYAN echoes asterisks rather than the actual typed text back to the modem. With the - parameter, BOYAN echoes 5.2.14: BOYAN Power--Macros and Script Files 100 ________________________________________________________________________ nothing at all; this can be used to read prompts from a BBS into a user variable. Finally, the + parameter tells BOYAN to "read with word wrap": if the input text exceeds the given maximum length y, then the previous word of input will be erased and saved for the next \RVc+ command. See the HOST.BSC script for many examples of how \RV is used. \SVc[string] \SV4[The current time is %HR:%MI:%SE.] Set Variable. This command lets you Set user Variable c. The example above sets variable %V4 equal to a message containing the current time. \TVc[y] \TV1[84] Terminal keyset macro into Variable. This command is analagous to the \MV command, moving the contents of BOYAN Secondary Keyset macro # y (41..110) into user variable c. \+Vc[y] \SV1[68] \+V1[34] \DM[ 68+34 = %V1 ] Plus Variable. This command lets your macros perform basic arithmetic. The number y is added to the contents of user variable c, and the result is again stored in variable c. To perform subtraction, let y be a negative number, e.g. \+V1[-34]. The valid range for numeric data is -10000..10000. In the example above, the \+V1[34] command changes the value of %V1 from 68 to 102. 5.2.15 Macro Control \\string \DL[] \\ that command downloads a file (Macro comment) BOYAN ignores all characters in a macro after the \\ command. Use this to insert remarks in a macro. BOYAN also ignores any spaces which immediately precede the "\\", so that you can use spaces to align comments in a script file. The above example has the same effect as "\DL[]" alone. \AB \KV2Y[Continue? ]\IV2+N[\AB]\DM[Continuing...] ABort current macro (or script file) processing. The example prompts the user with the "Continue?" prompt. If the user responds "N", the macro or script is aborted, and none of the following commands are processed. \AT+[macro] \AT+[\MM] \AT-[macro] \AT-[\PM[Script file %CS is running.]] ATtended? The \AT+ command processes the enclosed macro only if BOYAN is attended, that is, if there is no script file running. The \AT- command processes the enclosed macro only if BOYAN is not attended--when a script file is running. \EM \RE[ \DM[ %RE ] \CA+[\EM] ] End Macro: stops the current macro; if in a script file, advance to the next line of the script. This command is most often used to break out of an infinite REpeat loop. In the example above, BOYAN displays a 5.2.15: BOYAN Power--Macros and Script Files 101 ________________________________________________________________________ running counter until the CArrier signal is detected, at which point the \EM command breaks the loop. \IE+string1,string2[macro] \IE+%UD,DL[\DM[File downloaded.]] \IE-string1,string2[macro] \IE-0,%DS[\JD|\ST[Can't jump to DOS.]] If Equal? The \IE command tests the equality of string1 and string2. \IE+ processes the enclosed macro if the strings are equal; \IE- processes its macro only if they are not. The first example above displays the "File downloaded" message if the last file transfer was a download (the %UD variable would equal "DL"). The second example jumps to DOS if the amount of DOS Shell space (%DS) does not equal 0, and writes a status message if %DS does equal 0. Case is NOT significant, so ibm-PC matches Ibm-Pc. \II+string1,string2[macro] \II+Put,Computer[\DM['Put' found at position %II.]] \II-string1,string2[macro] \II-PCA,%V6[\DM[Error: %V6 should contain 'PCA'.]] %II %IM \II+;,%V8[\LV8[%IM]] If Included? The \II command tests If string1 is Included as a substring of string2, as "Put" is a substring of "Computer". \II+ processes its macro if string1 is included in string2; \II- processes macro if string1 is not in string2. The %II variable returns the numeric position within string2 where string1 was found, if \II+ was successful, so the first example macro above displays the message, "'Put' found at position 4". The %IM macro simply equals %II Minus one. This is used in the third example above to truncate %V8 at the position where a semicolon was found; e.g., if %V8 = Justin Boyan;ibm-pc, then processing the \LV8[%IM] macro leaves %V8 = Justin Boyan. \IK+[macro] \ST[Press any key: _] \RE[\IK+[\EM] ] \IK-[macro] %IK \IE-%IK,Q[\MA[61] |ELSE \AB] If Keypressed? \IK+ runs its enclosed macro only if a key has been pressed during the operation of the current macro or script block. \IK- runs its enclosed macro if no key has been pressed. The %IK variable always holds the last character typed by the user. The first example above repeatedly checks for a keypress, ending the macro once you press a key. The second example runs macro #61 if the last key you pressed was q; if the last key you pressed was not q, then the macro/script is aborted. Compare %IK with the \KV macro command described in section 5.2.14. The difference is that \KV stops macro processing to wait for user input, while %IK checks to see if you have typed anything while the macro is running. \MA[x] \MA[9] MAcro. This invokes BOYAN macro # x (1-120). For example, the macro command \MA[9] runs the initialization Auto-macro; \MA[38] invokes the <Alt-X> (exit BOYAN with verify) macro. 5.2.15: BOYAN Power--Macros and Script Files 102 ________________________________________________________________________ \REx[macro] \RE5[\WF[]] \RE[macro] \ST[Waiting for carrier...] \RE[\CA+[\EM]] %RE \RE24[\DM%RE[Hi there!]] REpeat macro. If a number x (1..32767) is given before the left bracket, then the enclosed macro will be executed x times. The first example above would wait for five characters to arrive from the modem. If no number is specified, the enclosed macro is repeated indefinitely. To break out of such an "infinite loop," the enclosed macro must contain an ABort, End Block, or End Macro command (or the user can abort by pressing <Esc>). Above, the \CA+[\EM] command is used to break out of the repeat loop as soon as the carrier signal is detected. The %RE variable holds the counter number of the innermost repeat loop. In the third example above, the message "Hi there" is displayed on line 1, line 2, line 3, ... all the way to line 24. 5.2.16 Miscellaneous \CB[] \AT+[\CB[]] \CB[c] \CB[T] Configure BOYAN. \CB[] invokes BOYAN's main configuration menu. If you specify a letter (any of S C D E M A T X) within the brackets, BOYAN will jump directly to the specified Config Area. The configuration choices must be made from the keyboard, so do not run this macro unless the keyboard is attended. \EX \KV0Y[OK to exit? ]\IV0+Y[\EX] EXit BOYAN immediately! A macro like the one above may be used to make the user confirm that he wants to exit. \HE HElp. This invokes BOYAN's main help screen, the BOYAN Command Menu. \HK Help with function Keys. This calls up BOYAN's screen of user-defined function key descriptions. \RB Review Buffer. This calls up the scroll-back buffer for viewing, script learning, etc. \SK+ \SK- \SK* %SK Secondary Keyset (Scroll locK). \SK+ sets Scroll-Lock ON, activating the Secondary Keyset of the current BAM. \SK- turns Scroll-Lock OFF, \SK* toggles Scroll-Lock, and %SK returns Scroll-Lock's current status (ON or OFF). 5.2.16: BOYAN Power--Macros and Script Files 103 ________________________________________________________________________ \SMx[string] \SM1[ATDT 9,"@SF"{] Set BOYAN Macro # x to the specified macro. This new macro is saved to the BOYAN.MAC file, just as if it were reconfigured in Config Area <M>. The example sets macro #1 (the Dialing command) to ATDT 9,@SF{ which is useful for dialing out from Centrex-type phone extensions. \TMx[string] \SN101["\HK] Set BOYAN Terminal Keyset Macro # x (41..110) to the specified macro. This new macro is saved to the .CNF file corresponding to the current BAM, e.g., VT-100.CNF, HOST.CNF, etc. Also see the \TV command above, which reads a macro from the secondary keyset into a user variable. 5.2.17 <Shift-F1> Trace Mode BOYAN's macro language provides a "trace" feature which can help you learn how a macro works or discover why a macro or script is not working. When Trace Mode is on, the middle of the Status Line always displays the two letters of the current macro command being processed. (When sending text to the modem, you will see a small arrow rather than two letters.) In addition, while a script file is running, the Status Line will indicate the current line number of the script being processed. An especially handy feature is the ability to slow down and speed up the script dynamically, as the script is running. When the Num-Lock toggle is not locked, the macro or script being traced will race along at normal speed. At this speed it is impossible to follow the trace output closely. When Num-Lock is locked, however, BOYAN pauses for approximately one-half second between displaying the macro's name and actually executing it. You may turn Num-Lock on and off at any time while a script is running. \NK+ \NK- \NK* %NK Num locK. \NK+ sets Num-Lock, \NK- unsets Num-Lock, \NK* toggles Num- Lock, and %NK returns Num-Lock's current status (ON or OFF). A handy debugging tool is to insert the \NK+ command at the position in your script where you are having trouble. When the script gets to precisely that point, it will slow down so that you can follow the Trace Mode output. \TR+ \TR- \TR* %TR The \TR+ and \TR- macros are used to actually turn Trace Mode on and off. \TR* toggles the Trace Mode, and %TR reports the current status (ON or OFF). 5.3: BOYAN Power--Macros and Script Files 104 ________________________________________________________________________ 5.3 BOYAN Macro Tutorial, Examples The best way to learn how BOYAN's macros work is to experiment: write one, and see what it does! The <Alt-M> "Enter macro manually" command is useful for trying out a short macro. Many example macros have already been given, next to the descriptions of all the macro commands. The following additional examples illustrate how BOYAN's 120 built-in macros give you flexibility unlike any other communications program. To edit the BOYAN macros, press <Alt-K>. You can then choose a macro for editing by either typing its number (1-120) and pressing <Enter>, or in the case of keystroke macros, simply pressing the keystroke (such as <F2>) itself. For a review of basic macro editing, please see section 3.9.4. Don't worry about destroying BOYAN's original macros while you experiment. You can always restore all of the preset macros by simply deleting the BOYAN.MAC file from your disk and starting BOYAN over. 5.3.1 Built-in Keystroke Examples This section studies some of the built-in BOYAN keystroke macros to show you how they work and to aid you in modifying them if you like. They are ordered roughly from simplest to most complex. > <F2>: Send your name + <Enter> < Macro #72: Justin Boyan{ The simplest kind of macro! The left curly brace stands for the <Enter> or <Return> character. > <F3>: Send your password + <Enter> < Macro #73: %PW{ When you a dial a system from the dialing directory, that system's private password is stored in BOYAN's %PW variable. This key macro sends that password and the <Return> character over the modem. > <Alt-F10>: Display current time and date < Macro #110: \ST[It is now %HR:%MI:%SE on %MO/%DA/%YR.] The \ST[..] macro command displays a string on the Status line. This example shows how Macro Variables may be used in such a string. > <Alt-N>: New disk directory < Macro #28: \KV0%C:[NEWDIR: ] \ND[%V0] \ST[%C:] This example shows how BOYAN's interactive macros work. First, the macro uses the "\KV#default[prompt]" command to prompt the user for input. In this case, the user's prompt is "NEWDIR: "; the default response is %C:, a variable which returns the name of the current disk directory; and the user's final response is kept in user variable #0. 5.3.1: BOYAN Power--Macros and Script Files 105 ________________________________________________________________________ Then, the \ND[%V0] command switches to a New Directory given by %V0. Finally, the \ST command displays a status message, consisting of simply the (new) current disk directory. > <Shift-F1>: Toggle BOYAN's "Trace Mode" < Macro #39: \TR* \ST[Macro trace mode now %TR] First, the \TR* command has the effect of actually toggling the Trace Mode setting. Then, a status message is displayed which includes the new value of the Trace Mode variable %TR, either ON or OFF. This macro is typical of BOYAN toggle commands. (The trace mode itself is very useful for understanding macros and scripts; see section 5.2.17.) > <Alt-L>: Toggle Disk Logging < Macro #26: \IE+OFF,%LD[\KV0%LN[Log to: ]] \LD*[%V0] \ST[Logging now %LD] This is another toggle command like <Shift-F1>, but it inserts an extra conditional command at the beginning. The conditional (If Equal) command checks if logging to disk (%LD) is equal to OFF. If so, then the \KV command prompts the user for a filename to "Log to", giving the default log name (%LN) as a default. > <F6>: View usage log < Macro #76: \DC[%LC %UN] This macro uses the \DC[..] macro to execute a DOS Command. The %LC variable names your file lister program (specified in Config Area D). The %UN variable contains the name of your usage log file. Putting these together, the DOS command that <F6> executes looks like "LIST C:\BOY5\BOYAN.USE". Similarly, you can assign any DOS command to a single keystroke. > <Ctrl-F1>: View the BOYAN.DOC file, this user's manual < Macro #81: \SV0[%B:BOYAN.DOC] \FE+%V0[\DC[%LC %V0] | \ST[File not found.]] This macro adds complexity to the <F6> example above because it checks that the file exists before trying to view it. In this case, the file to be viewed is BOYAN.DOC, which if it exists is assumed to live in your BOYAN home directory (specified by %B:). Here's how the macro works. First, it sets user variable 0 to hold the full name of the file, %B:BOYAN.DOC. Then it uses the \FE+ macro to check that the file exists. If it does, the macro calls DOS to list the file; otherwise (|), it prints a "File not found" status message. > <Alt-V>: View file using File Manager < Macro #36: \( \KV0[VIEW: ] \RS \IV0+[\FMV[] |ELSE \DC[%LC %V0]] Macro #119: \KS \DM1,24[ (Leave blank for directory.) ] If a key macro is too long to fit in the space provided, one solution is to break it up into two separate macros. The <Alt-V>, <Alt-R>, and <Alt-W> key macros all make use of macro #119, the \( Shortcut macro. This shortcut does two things: it stores an image of the current screen in memory (\KS), and it displays a brief message on line 24. After 5.3.1: BOYAN Power--Macros and Script Files 106 ________________________________________________________________________ invoking the shortcut \(, the <Alt-V> macro prompts the user for a filename, and then restores the screen (\RS), thus un-displaying the "Leave blank for disk directory" message. Finally, the \IV0+[...] command tests whether the user's response (%V0) was empty. If it was, then the File Manager is invoked with "View" as the default selection (\FMV[]); otherwise, the <Alt-V> macro calls DOS to view the file immediately. 5.3.2 Auto-macro Examples > Clear screen automatically before dialing < Macro #1: \ZS ATDT@SF{ BOYAN dials a number by simply executing Macro #1, the dialing command. The @SF variable is used to insert the System FON number into the command. To make BOYAN automatically clear the terminal screen before dialing, just insert the command \ZS (Zap Screen) into macro #1. > Remove same-named systems from Queue after connect < Macro #6: \UM[%SN (%MS baud): %SF] \QA-[%SN] When you connect to a system, BOYAN automatically deletes that system from the Redialing Queue. However, by appending the \QA-[%SN] command to macro #6, you instruct BOYAN to also delete from the Queue any other systems with a similar System Name. For example, suppose you have systems named "Bob's BBS Line 1", "Bob's BBS Line 2", and "Bob's BBS Line 3" all in the Queue. When you connect to any one of those systems, this macro will automatically remove all three systems from the Queue. > Eliminate the "squawk" BOYAN makes after disconnecting < Macro #7: \RC \SK- \UM[| Disconnected after %SL] Simply delete the \AL3[0] command from the "After disconnecting" Auto-macro (#7). > Automatically return to dialing directory after disconnecting < Macro #7: \AL3[0] \RC \SK- \UM[| Disconnected after %SL] \DI[] As soon as the connection's carrier signal is lost, BOYAN executes its Auto-macro #7. By adding the command "\DI[]" to the end of macro #7, you instruct BOYAN to automatically invoke the dialing directory after disconnecting. > Automatically log all sessions to disk < Macro #6: \UM[%SN (%MS baud): %SF] \LD+[%B:BOYAN%S#.LOG] Macro #7: \AL3[0] \RC \SK- \UM[| Disconnected after %SL] \LD- If you add these \LD commands to Auto-macros #6 and #7, BOYAN will automatically maintain a separate, permanent log file for each dialing directory entry. The log files will be stored in the BOYAN home directory (%B:) and named BOYAN1.LOG, BOYAN2.LOG, ... BOYAN200.LOG, depending on the system's entry number in the dialing directory (%S#). The appropriate log file is opened by Macro #6 whenever you make a connection and closed by Macro #7 (\LD-) as soon as you disconnect. 5.3.2: BOYAN Power--Macros and Script Files 107 ________________________________________________________________________ Thanks to Auto-macro #14 (the "Log file init macro"), a header line will separate the sessions within each system's log file. > Log each day's sessions to a dated disk file < Macro #9: ATX4S0=0{ \LD+[%B:%MO-%DA-%YR.LOG] Unlike the previous example, where the name of the log file depends on which system you call, this example opens a log file whose name depends on the current date. Every time you start BOYAN, this start-up macro (#9) will open a log file in the BOYAN home directory (%B:) named by the current date, e.g., 05-28-92.LOG on May 28, 1992. BOYAN's conclude macro contains the \LD- command, so the log will be closed when you exit BOYAN. > Automatically fill the redialing queue at BOYAN start-up < Macro #9: \DM[ Welcome to BOYAN! ] ATX4S0=0{ \QA[1] \QA[4] \QA[5] Suppose you dial systems 1, 4, and 5 in your dialing directory every time you use BOYAN. If you append the commands \QA[1] \QA[4] \QA[5] to the BOYAN start-up macro (#9), then those three systems will automatically appear in the redialing queue. You could also append either of the \QE (enter redialing queue) or \QD (begin queue redialing) commands. > Report the current Action Module name at start-up < Macro #9: ATX4S0=0{ \ST[Using Action Module: %AN] After initializing the modem with ATX4S0=0 <Return>, this BOYAN start-up macro will display a status message such as "Using Action Module: VT-100". The %AN variable holds the name of the current action module. > Get path confirmation before starting auto-download < Macro #12: \AT+[\DL[]] Remove the "-" from the default Auto-download macro to make BOYAN wait for you to confirm the download path before beginning an auto-download. > Dial multiple systems in the middle of the night < Macro #99: \QC \QA[Joe] \QA[Liz] \QA[Bob] \PU[3] \QU[6] Macro #7: \UM[| Disconnected after %SL] \QU[6] Let's see how these work. Macro #99 corresponds to the <Shift-F9> key. The first thing that happens when you press <Shift-F9> is that the queue is cleared. Then, the \QA command adds systems to the queue from the Dialing Directory. \PU tells BOYAN to Pause Until 3:00 am, at which point \QU will tell BOYAN to begin Queue redialing--but to give up at 6 am if no connection has been made. If a connection is made, however, then Macro #99 will finish, and the auto-logon script for that system (say, JOE.BSC) will take over. This script might read your mail on Joe's BBS and capture it to a file, for example (see section 5.5). At some point, JOE.BSC logs you off from the BBS. Here's where macro #7, the "After Disconnecting" Auto-macro, comes into play. As soon as the carrier signal drops, Macro #7 wakes up, 5.3.2: BOYAN Power--Macros and Script Files 108 ________________________________________________________________________ records a message in the usage log, and begins redialing again with the \QU command. The systems that remain in the queue (Liz and Bob) will be handled just like Joe's, as soon as a connection is made. At 6 am, queue redialing will stop, even if there are some systems which haven't yet been reached. 5.3.3 Yet More Key Examples! > Make <Home> call up the BOYAN Command List < Macro #45: \HE > Make left mouse button invoke the Dial Directory < Macro #11: \DI[] > Make left mouse button run the MOUSMENU.BSC script < Macro #11: \SC[MOUSMENU] This demonstrates how you can link the mouse button (or any function key) directly to a script file. > Make <Alt-D> offer a "Quick-Dialing" bar < Macro #18: \KV0[DIAL: ] \DI[%V0] If you alter the <Alt-D> keystroke macro (#18) as above, then instead of going straight to the Dialing Directory, <Alt-D> will prompt you with "DIAL:" on the Status Line. First, the \KV0 command requests your input, storing what you type in user variable %V0. Then the \DI[%V0] command dials that number, whether it is the name of a system from the Dialing Directory, the code number of a system from the directory, or a full phone number entered manually. If you typed only <Enter>, then %V0 would be empty, so \DI[%V0] conveniently would invoke the Dialing Directory. > Make <Alt-0> "Kill" all BOYAN sound effects < Macro #69: \BB- \AV[0] \ST[Sound effects Killed.] Now the <Alt-0> command (macro #69) will both turn Beeps & Bells off and set the Alarm Volume to 0. As a friendly touch, it will also display a status message. > Make <F9> invoke your editor on the last script file run < Macro #79: \DC-[%WC %S:%SC] This macro makes a handy command by combining three macro variables: %WC, which holds the name of your word processor/text editor; %S:, the script directory, and %SC, the last script file run. It concatenates them to form a string such as "QEDIT C:\BOY5\SCRIPT\CIS.BSC", and then executes that string as a DOS Command. The - in \DC- tells BOYAN not to wait for you to press a key after returning from the editor. 5.3.3: BOYAN Power--Macros and Script Files 109 ________________________________________________________________________ > Make <PgUp> remember the directory of the last upload < Macro #47: \UL[%T:] BOYAN's normal upload macro, \UL[], chooses your Upload Directory (as specified in Config Area <D>) as the default path to search for the upload filename. This macro tells \UL to search the path given by %T: instead, where %T: stores the path used by the previous file transfer. > Make <End> reset the current modem port < Macro #46: \CD[%MD] The trick is to tell BOYAN to "change devices" to the current modem device--resetting the device in the process. This is what the <End> keystroke macro (#45) above does. Running certain external programs may cause the port to "lock up"; if that happens, running this macro (by pressing <End>) should fix the problem. > Make <Alt-F5> toggle the "GOSSIP" Action Module < Macro #105: \IE-%AN,GOSSIP[\AM[G] |ELSE \AM[%AP]] The \AM macro command selects a new BOYAN Action Module; for example, \AM[G] invokes BOYAN's Gossip Mode. The <Alt-F5> keystroke macro (#105) presented above is more sophisticated: if you are already in Gossip mode, pressing <Alt-F5> again will return you to your prior Action Module. Here's how it works: the \IE- command checks to see If the current Action module Name, %AN, is not Equal to "GOSSIP". If they are not equal, then the Gossip Mode is invoked by "\AM[G]". Otherwise, if GOSSIP is the current name, then the previous module is invoked with "\AM[%AP]". (The %AP variable remembers the previous Action module letter.) > Make <Ctrl-F8> view the contents of a ZIP file < Macro #88: \FM`pkunzip -V[*.ZIP] This macro invokes the File Manager on all .ZIP files in the current directory. The default command for the File Manager is given as PKUNZIP -V, which is the DOS command to view the contents of a ZIP file. > Make <Ctrl-F9> build a ZIP of selected files < Macro #89:\FML[] \KV0[Build zip:] \DC-[pkzip %V0 "@boymark.lst] \ST[Done!] First, this macro invokes the File Manager with the List command as default. While in the File Manager, you may use the <space> key to mark files, and then <Enter> to list those files to the BOYMARK.LST file. The macro then prompts you for the name of the .ZIP file to build, and invokes the DOS Command PKZIP @BOYMARK.LST to actually build the .ZIP using the filenames in BOYMARK.LST. > Make <Shift-F10> turn BOYAN into an alarm clock < Macro #100: \KV0%HR:%MI[Set alarm: ] \UT%V0[\DM[ %HR:%MI:%SE ]] \AL2[3] This macro uses several advanced commands. The first command, \KV0%HR:%MI[Set alarm: ], requests keyboard input into user variable %V0 with the prompt, "Set alarm: ". A default of %HR:%MI, the current time, 5.3.3: BOYAN Power--Macros and Script Files 110 ________________________________________________________________________ is provided. The second command, \UT%V0[\DM[ %HR:%MI:%SE ]], loops Until the Time has become %V0--which is the time read in from the keyboard. During each loop it Displays a Message of the current time on the screen. When the \UT loop finally finishes, the third command, \AL2[3], rings an alarm (type 2) for three seconds. * * * * The macros above are just a small sample of the range of flexibility BOYAN's built-in macros can offer. If you write a clever macro, please submit it for inclusion in the next edition of this manual! 5.4 The BOYAN Command Line Normally, you run BOYAN by issuing the simple command BOYAN from DOS. BOYAN's first step is to execute Auto-macro #9, the BOYAN start-up macro. However, in some cases, you may wish to avoid BOYAN's start-up macro. BOYAN allows you to specify an alternative start-up macro when invoking BOYAN, directly from the DOS command line. For example, if you ran BOYAN with the DOS Command BOYAN ATZ{ , then BOYAN would send the ATZ <Return> modem string, rather than executing macro #9. If you invoked BOYAN by typing BOYAN \DI[Boyan Support] , then BOYAN would immediately dial the specified number. If you ran BOYAN with the command BOYAN \\ , then BOYAN would do nothing at all at start-up (bypassing its normal start-up macro), since \\ signifies only a macro comment. This might be useful if you were already on-line before invoking BOYAN. Another application of the command line macro feature is that BOYAN can be run from a batch file. For example, a batch file could invoke BOYAN with the command, BOYAN \MA[9] \SC[NIGHT] . At start-up, BOYAN would first run macro #9 (the normal start-up macro), and then execute the NIGHT.BSC script file. Your DOS command line may also specify the amount of memory BOYAN should reserve for the DOS Shell. For example, type BOYAN 100 to have BOYAN reserve 100K of memory for the Shell. A start-up macro could follow the memory specification; e.g., BOYAN 100 \MA[9] \DI[Boyan Support] would make BOYAN reserve 100K of memory for DOS, execute its normal start-up macro, and finally dial the Boyan Support BBS. 5.5: BOYAN Power--Macros and Script Files 111 ________________________________________________________________________ 5.5 Script Files BOYAN script files can be created by any text editor or word processor which can edit standard text files--for instance, the EDLIN editor which comes with DOS, or the SideKick notepad. Script files must be named with a suffix of .BSC, and should be placed in the default BOYAN script directory (although that is not mandatory). The simplest kind of script file is just a sequence of BOYAN macros. BOYAN processes such a script file by sequentially evaluating each line of the file as a macro, until it reaches the end of the file. Blank lines are ignored. This is the type of script created by BOYAN's auto- matic Script Learn facility. In more complex script files, you may organize the sequence of macros into as many as 500 "blocks." The start of a block is defined by a line of text which begins with the vertical bar | symbol (shift- backslash) plus a block label. Labels can be as long as you wish, but only the first eight characters are significant, e.g., MessageReply and MessageRead are equivalent labels. Since case is not significant, |LOGON and |LogOn also refer to the same block. All macros following a block label are considered a part of that block until either another block label or the end of the file is reached. 5.5.1 Script-specific Macro Commands The Macro Programming Language provides several additional commands specifically for power in script files. These commands allow BOYAN scripts to use looping, block nesting, and even recursion. \AB ABort. Aborts all current script files, just as if you had pressed the <Esc> key. If the script has a block named *WRAPUP in it, that block will be executed before you are returned to terminal mode (see section 5.5.4). \BL[label] \BL[LogOn] BLock. Calls the block with the specified label. When that block has completed, control is returned to the calling macro. \EB \IF+end of messages[\EB] End the current Block. You can use this within a conditional statement to end the block prematurely. See also \EM (End Macro). \GB[label] \GB[LogOn] Goto Block. Go directly to the block with the specified label. When the end of that block is reached, the script is finished; control is not returned to the calling macro. 5.5.1: BOYAN Power--Macros and Script Files 112 ________________________________________________________________________ \GS[filename] \GS[rbbs] \GS[filename;label] \GS[rbbs;messages] Goto Script. Go directly to the script with the specified filename (.BSC suffix assumed). If a semicolon and label are given, the specified block of the script is executed; otherwise, the entire script runs from start to finish. \KO[x] \KO[0] Keyboard timeOut. Set the unattended keyboard timeout to x seconds. If BOYAN requires keyboard input while a script file is active, it will wait x seconds for the user to manually respond. If there has been no keyboard response after x seconds, BOYAN goes ahead using the default response. After the \KO[0] command, for example, BOYAN automatically accepts the default response immediately. %S: D:\BOYAN\SCRIPT\ %SC PCBOARD.BSC Script path. The %S: variable contains BOYAN's script file disk drive+path; %SC holds the name of the currently active (or most recently active) script file. \SC[filename] \SC[rbbs] \SC[filename;label] \SC[rbbs;LogOn] SCript. Invoke the script with the specified filename (.BSC suffix assumed). If a semicolon and label are given, the specified block is executed; otherwise, the entire script runs from start to finish. When that script has completed, control is returned to the calling macro. If the filename is not preceded by a DOS pathname, BOYAN assumes that the script file is located in the default Script directory. 5.5.2 Automatic Logon Scripts In section 4.7.3.1, you saw how BOYAN's Script Learn Facility could be used to write scripts for automatic logging-on to a system. BOYAN allows a completely hands-free logon through its dialing directory Script field. Using the Edit command in the dialing directory, you can assign each entry a 1-8 character script name, like PC-BOARD or MCIMAIL . The next time you connect to the system using the <Alt-D> Dial or <Alt-Q> Queue Redial commands, BOYAN loads the specified script file (the .BSC suffix is automatically added). It then searches for a block labeled |LOGON. If there is a |LOGON block in the script, then only that block is executed. Otherwise, the entire script is processed from beginning to end. 5.5.3: BOYAN Power--Macros and Script Files 113 ________________________________________________________________________ 5.5.3 Running Script Files BOYAN can automatically process a logon script file after making a connection. However, you may often need to run a script at some other time. BOYAN provides a number of convenient methods for executing either an entire script file or just a single block from a script file. When specifying a script file, you may include the script's directory, its name (.BSC suffix assumed), and optionally a semicolon and a block label. For example, the following are all valid script specifiers: c:\text\menu;DownLoad This specifies the drive, directory, script name (MENU.BSC), and block to execute. RBBS.BSC;LogOn This specifies the LOGON block of the RBBS.BSC script. BOYAN will search for this script first in the Script Directory (set in Config Area <D>). If it is not found there, BOYAN will also look for it in the current directory. A:INIT This specifies the A:INIT.BSC script, but no particular block. BOYAN will run the entire script from start to finish. Besides specifying an auto-logon script, you can run a script file in the following ways: 1. Use BOYAN's <Alt-R> command from terminal mode. Respond to the "SCRIPT:" prompt with a specifier like any of the three examples above. If your response is blank, you will be given the chance to select a script directly from your Script Directory. 2. Select the script file directly from the <Alt-F> Directory File Manager (section 4.6.1). If the file cursor is over a file with a .BSC suffix, pressing E will execute the script. 3. Use the \SC[filename;label] command in any BOYAN macro. For example, you could assign a function key to the macro \SC[tcomm;DownLoad] . Another use might be to set macro #9 (Start-Up macro) or macro #10 (Conclude macro) to have BOYAN automatically run a STARTUP.BSC or CONCLUDE.BSC script each time it starts or concludes. You can also invoke a script file directly from the DOS command line, as described above in section 5.4. 5.5.4: BOYAN Power--Macros and Script Files 114 ________________________________________________________________________ 5.5.4 During Script Execution Once a script file takes control, the BOYAN v5 message in the middle of the status line disappears, and the script file name flashes in its place. When this happens, BOYAN is "unattended" and its normal terminal mode commands are disabled. To regain control before the script file finishes, you must press the <Esc> key. The <Tab> key also has a special function during script execution. If you press <Tab>, the script stops whatever task it is in the middle of and jumps to the block labelled *TAB. It is as if pressing <Tab> inserts the command \GB[*TAB] into the middle of your script. The Host Mode script uses this feature to make the Sysop Menu available at all times. Another special script block is the *WRAPUP block. Whenever a script finishes, either normally or by <Esc>, BOYAN searches for and executes a block in that script named *WRAPUP. Consult HOST.BSC and ETCH.BSC for examples of how to use *WRAPUP. 5.5.5 Script Examples Several sample script files are included on the BOYAN Distribution Diskettes. These scripts are well-commented, so by studying them, you can learn a lot about writing your own scripts. - CIS.BSC is a simple script file for logging on to the CompuServe Information Service. You must use a text editor to include your own CompuServe ID in the script file. - ETCH.BSC demonstrates macro screen control by turning BOYAN into a computer etch-a-sketch! After invoking this script (with the <Alt-R> command), use the I,J,K, and M keys to "draw" on the screen. Press <Esc> to exit the script. - HOST.BSC contains the complete BOYAN Host Mode. This script is very complex, using extensive branching, file transfers, DOS commands, macro arithmetic, and BOYAN Auto-macros. Section 4.8 describes how to use the Host Mode. - PCBOARD.BSC is a simple logon script file for the PC-Board type of Bulletin Board System. It expects that macro #72 (the <F2> keystroke macro) contains your full name + the { symbol. By configuring this keystroke macro and entering your password into the Dialing Directory entry, you do away with the need to edit the PCBOARD.BSC file. 5.5.5: BOYAN Power--Macros and Script Files 115 ________________________________________________________________________ - TCOMM.BSC is a logon script file for TComm Bulletin Board Systems. It also expects your name + { to be stored in macro #72. This script demonstrates a very flexible method for responding to prompts regardless of the order in which they arrive. - VARS.BSC displays the 36 user variables in two full-screen displays. BOYAN's Trace Mode (section 5.2.17) is a terrific aid in following a script as it runs. Many other script files written by BOYAN users are available for downloading from the BOYAN Support BBS. 5.5.6 Technical Notes 5.5.6.1 The Macro Compiler Macros are automatically compiled as they are run; there is no separate compiling stage. When interpreting text enclosed in brackets, the compiler makes a distinction depending on whether the text is a [string] or a [macro]: - In a string, the first unquoted right bracket always denotes the end of the string; in order to include a right bracket inside a string, you must precede the bracket with a quotation mark. For example, to make BOYAN WaitFor the "Press [Enter] to continue" message, you must write: \WF[Press [Enter"] to continue] As a string is compiled, all macro variables contained in it are expanded. - However, in commands which have a [macro] in their syntax (the \RE, \UN, \UT, and all conditional commands), the compiler automatically matches internal brackets. For example, to REpeat (5 times) the command \RX[1] \RY[1], you would simply write, \RE5[\RX[1] \RY[1]] without having to quote the brackets inside. Variables are not expanded inside macros; for example, the macro \UT`12:00[\DM[%HR:%MI:%SE]] displays a running clock on the screen until noon, rather than just displaying whatever the time was when you first invoked the \UT command. 5.5.6.1: BOYAN Power--Macros and Script Files 116 ________________________________________________________________________ The macro processor ignores spaces and tabs between macro commands. If you actually want to send a number of spaces to the modem, add a "dummy" backquote following those spaces, as in here come five spaces ` Alternatives are to precede each space with a quotation mark, or to use the macro \CH[32]. 5.5.6.2 Variable Prefixes: % vs. @ BOYAN Macro Variables may be referred to with either the % or the @ prefix. When a variable is specified by %, then any special macro command characters (such as ^ % @ \ ` , etc.) are automatically quoted with ". When specified by @, no extra quoting is done. For example, assume that variable V0 holds the string D:\UL. If a macro referred to that variable as %V0, BOYAN would add a quotation mark before the \, as it does before every special character. As a result, BOYAN would send the literal string D:\UL to the modem. It does not treat \UL like a macro command, but rather like a bunch of characters. Now, change the % to a @, making the variable @V0. In this case, BOYAN does not add a quotation mark before the \. It would send the D and : over the modem and report a syntax error on the \UL macro command. Thus, one use for the @ variable prefix is to execute the contents of a variable as if they made up a BOYAN macro. This is why the Dialing Command refers to the System Fon number as @SF rather than %SF--so that Shortcut macros, etc. may be used within the phone number. A similar application of the @ prefix can be seen in the <Alt-M> macro. Another use of the @ prefix is to force the evaluation of a variable which is used within another variable. For example, suppose at 1:15 pm you set V1 and V2 as follows: \SV1[Time is %HR:%MI] (This sets V1 = Time is 13:15.) \SV2[Time is "%HR:"%MI] (This sets V2 = Time is %HR:%MI.) If you displayed these variables on the monitor five minutes later, you would get the following results: \DM[%V1] displays, Time is 13:15 \DM[@V1] displays, Time is 13:15 \DM[%V2] displays, Time is %HR:%MI \DM[@V2] displays, Time is 13:20 5.6: BOYAN Power--Macros and Script Files 117 ________________________________________________________________________ The automatic quoting done in interpreting %V2 means that %HR is displayed, not evaluated. In contrast, @V2 substitutes the contents of V2 directly into the \DM[..] command, so %HR and %MI are evaluated. 5.6 Summary of Macro Variables %AM The menu letter corresponding to the current Action Module %AN The full Name of the current Action module %AP The menu letter corresponding to the Previous Action module %AU current state of AUto-downloading, "ON" or "OFF" %B: The complete path of the BOYAN directory %B8 "ON" when eighth Bit allowed, "OFF" when eighth Bit stripped %BB current Beeps and Bells setting, "ON" or "OFF" %BD "ON" when Backspace key sends DEL, "OFF" when backspace sends BS %BU "ON" when 16550AN UART FIFO buffering is enabled, "OFF" when disabled %C: The complete path of the Current directory %D: The complete path of the default Download directory %DA The current DAy of the month (01,02,..31) %DM The current color used for Displaying macro Messages %DN The Name of the screen Dump file %DP The Default Protocol %DR The letter corresponding to the currently-logged DRive %DS The amount of memory (in K) available for DOS Shells %EC Current ECho keyboard setting, "ON" or "OFF" %F: The complete path where BOYAN expects to find .FON Directories 5.6: BOYAN Power--Macros and Script Files 118 ________________________________________________________________________ %FD The name of the current .FON Directory %GL The number of Grabbed screen Lines (25, 43, or 50) %HR The current HouR (00,01,..23) %II The position of string1 as a substring of string2 determined by the last \II macro %IK The last Input Key typed at the keyboard %IM %II Minus one %LC The List Command (DOS command to list a file) %LD "ON" if currently Logging to Disk, "OFF" if no log file open %LF "ON" if LineFeeds are being added to CR's, "OFF" if not %LN The Name of the most recently-selected Log file %LV The Length of the Variable most recently accessed with the \LV command %MA The current Modem port Address, in hexadecimal (without the $ sign) %MC The current Menu Color (1..127) %MD The number of the current Modem Device (1..4) %MI The current MInute (00,01,..59) %MM Maximum Modem speed as entered in Config Area <C> %MN The current Modem iNterrupt IRQ line (2..5) %MO The current MOnth (01,02,..12) %MP The letter corresponding to the current Modem Parity (N, E, or O) %MS The current Modem Speed (300..38400) %NC The current Normal text Color (1..127) %NK Current Numlock setting, "ON" or "OFF" 5.6: BOYAN Power--Macros and Script Files 119 ________________________________________________________________________ %P: The complete path of the external Protocol directory %PR Current PRinter log setting, "ON" or "OFF" %PW Your PassWord for the currently online system %QS The Queue Size (number of entries in redialing queue, 0..20) %RE The counter number of the innermost \RE (REpeat) macro command %S: The complete path of the Script file directory %S# The phone directory code number of the currently online System (1..200, or 0 if dialed manually or not online) %SC The name of the current SCript file running (or last script file run) %SE The current SEcond (0..59) %SF The phone number of the currently online System %SK The Secondary Keyset (scroll lock) setting, "ON" or "OFF" %SL The Length of time since the last connection to a remote System %SN The Name of the currently online System (or "Manual" if dialed manually) %SS The name of the logon Script file (not including .BSC suffix) of the currently online System %T: The complete path of the most recent file Transfer %TF The name of the most recent File selected to be Transferred %TI A string with Transfer time Information, suitable for including in BOYAN.USE usage log %TR Current TRace mode setting, "ON" or "OFF" %TT Current Translation Table setting, "ON" or "OFF" %U: The complete path of the default Upload directory 5.6: BOYAN Power--Macros and Script Files 120 ________________________________________________________________________ %UD This variable equals "UL" if the last file transfer was an upload, or "DL" if the last file transfer was a download %UF Current Usage File log status ("ON" or "OFF") %UN The Name of the current Usage file %V0 Macro variable #0 %V1 Macro variable #1 %V2 Macro variable #2 . . . %V8 Macro variable #8 %V9 Macro variable #9 %VA Macro variable A %VB Macro variable B . . . %VY Macro variable Y %VZ Macro variable Z %WC The Word processor Command (DOS command to edit a file) %XP The current X-position of the cursor (1..80) %YP The current Y-position of the cursor (1..49) %YR The current year (91,92,..) 5.7 Summary of Macro Commands \\ signifies that the rest of the line is a comment, not to be processed as a macro ^c send control character to modem { send <Return> character to modem (same as ^M) ~ pause one-half second 5.7: BOYAN Power--Macros and Script Files 121 ________________________________________________________________________ \! Invoke Shortcut macro #111 \@ Invoke Shortcut macro #112 \# Invoke Shortcut macro #113 \$ Invoke Shortcut macro #114 \% Invoke Shortcut macro #115 \^ Invoke Shortcut macro #116 \& Invoke Shortcut macro #117 \* Invoke Shortcut macro #118 $ Invoke Shortcut macro #119 $ Invoke Shortcut macro #120 \AB ABort current macro or script file \AD+ Turn on Auto-Detection of modem connect speed \AD- Turn off Auto-Detection of modem connect speed \AD* Toggle between \AD+ and \AD- \AFfilename[string] Append string to the end of specified text File (creating file if not found) \ALx[] Sound ALarm x (1,2,or 3) until a key is pressed \ALx[0] Sound ALarm x (1,2,or 3) just once \ALx[y] Repeatedly sound ALarm x (1,2,or 3) for y seconds \AM[] Select a new BOYAN Action Module from a menu \AM[c] Activate the BOYAN Action Module corresponding to the character c \AT+[macro] Do macro if BOYAN is ATtended (no script file running) \AT-[macro] Do macro if BOYAN is not ATtended (script file running) \AU+ Turn AUto-downloading on 5.7: BOYAN Power--Macros and Script Files 122 ________________________________________________________________________ \AU- Turn AUto-downloading off \AU* Toggle AUto-downloading \AV[x] Set Alarm Volume to x (0..10, 10 highest) \B8+ Accept Bit 8 of incoming characters (no stripping) \B8- Strip Bit 8 from incoming characters \B8* Toggle between \B8+ and \B8- \BB+ Turn Beeps & Bells on \BB- Turn Beeps & Bells off \BB* Toggle Beeps & Bells \BC Back over Character, but do not put character into backspace buffer \BD+ Swap the Backspace and DEL keys \BD- "Unswap" the Backspace and DEL keys \BD* Toggle between \BD+ and \BD- \BL[label] Script file -- call the labelled BLock as a subroutine \BU+ Enable BUffering on the 16550AN UART \BU- Disable BUffering on the 16550AN UART \BU* Toggle between \BU+ and \BU- \BW+ Back over Word, putting erased characters into backspace buffer \BW- Back over Word, without putting erased characters into backspace buffer \CA+[macro] Do macro only if there is a CArrier signal (online) \CA-[macro] Do macro only if there is no CArrier signal (offline) \CB[] Configure BOYAN, main configuration menu 5.7: BOYAN Power--Macros and Script Files 123 ________________________________________________________________________ \CB[c] Configure BOYAN, go directly to Config Area [c] \CC+ Do Check for Carrier signal before dialing, and prompt user to verify "dialing despite carrier" \CC- Do not Check for Carrier signal before dialing, and dial right away \CC* Toggle between \CC+ and \CC- \CD[x] Change Device to 1,2,3,or 4 (Comm port #) \CF+ Check Free disk space before downloads and in file manager \CF- Do not Check Free disk space before downloads and in file manager \CF* Toggle between \CF+ and \CF- \CH[x] Send the ASCII CHaracter with code x (0..255) over the modem \CM Change Menu -- for changing device, speed, or parity \CO[x] Set the COnnect wait time to x seconds (0..99) \CP[c] Change Parity to [N]one, [E]ven, or [O]dd. \CS[x] Change Speed to 300, 1200, 2400, 4800, 9600, 19200, or 38400. \CT+ Turn CTS/RTS flow control on \CT- Turn CTS/RTS flow control off \CT* Toggle CTS/RTS flow control \DC[string] Execute string as a Dos Command, prompting for a user keypress if not inside a script file \DC+[string] Execute string as a Dos Command, prompting for keypress afterward \DC-[string] Execute string as a Dos Command, but do not prompt for a keypress afterward \DD+ Do Drop the DTR signal when you exit from BOYAN 5.7: BOYAN Power--Macros and Script Files 124 ________________________________________________________________________ \DD- Do not Drop the DTR signal when you exit from BOYAN \DD* Toggle between \DD+ and \DD- \DI[] Invoke BOYAN DIaling Directory \DI[x] DIal entry # x (1..200) from current dialing directory \DI[string] DIal the first dialing directory entry whose name contains string \DI[###-####] Manually DIal the phone number specified \DL[] Download file, prompting for protocol and filename \DL-[] Download file immediately using default protocol, bypassing all prompts \DLc[] Download file using protocol c \DLc-[] Download file immediately using protocol c, bypassing all prompts \DL[filename] Download specified file using default protocol, prompting for confirmation \DL-[filename] Download specified file, bypassing all prompts \DLc[filename] Download specified file using protocol c, prompting for confirmation \DLc-[filename] Download specified file using protocol c, bypassing all prompts \DMC[x] Set Display Message Color to x (1..255). Colors above 128 are flashing. \DM[string] Display Message string flushed right one line above current line \DMy[string] Display Message string flushed right on line y (1..49) of screen \DMx,[string] Display Message string at column x, one line above current line \DMx,y[string] Display Message string at position x (1..80), y (1..49) 5.7: BOYAN Power--Macros and Script Files 125 ________________________________________________________________________ \DP[c] Set Default Protocol for file transfers to c \DT+ Turn modem DTR signal ON \DT- Turn modem DTR signal OFF \DT* Toggle modem DTR signal \DVc[x] Delete the first x characters from variable c (0..9,A..Z) \EB End current Block of script file \EC+ Do ECho keyboard locally \EC- Do not ECho keyboard locally \EC* Toggle between \EC+ and \EC- \EM End the current Macro (advance to next line of script) \EX EXit BOYAN immediately. (Be careful with this one!) \FC Forward Character -- send most recent character saved in Backspace buffer \FD[filename] Load filename as the new .FON Dialing Directory. \FE+filename[macro] Do macro only if filename exists \FE-filename[macro] Do macro only if filename does not exist \FM[filename] Invoke BOYAN's File Manager. Filename can be a complete drive, path, and file specification (with wildcards). \FMc[filename] Invoke File Manager as above, but make <Enter> the same as selecting option c \FMstring[filename] Invoke File Manager as above, but make <Enter> apply the DOS command string to the selected file(s) \FS[c] Show Free Space on specified disk drive \FW Forward Word -- send characters from Backspace buffer until reaching a space 5.7: BOYAN Power--Macros and Script Files 126 ________________________________________________________________________ \GB[label] Go to Block specified by label (within current script) \GL+ Grab screen Lines ON (43 with EGA monitor, 50 with VGA) \GL- Grab screen Lines OFF (return to 25-line screen) \GL* Toggle between \GL+ and \GL- \GS[filename] Go to Script filename (.BSC extension optional) \GS[filename;label] Go to Script filename, block label \GVc[] Close the text file read by \GVc[filename] \GVc[filename] Get next line from specified text file into variable c \GX[x] Go to X position x (1..80) \GY[y] Go to Y position y (1..49) \HE Call up HElp screen (from "Communication Ready" screen only) \HK Call up Help on function Key descriptions \HU Hang up modem \IE+str1,str2[macro] Do macro only If str1 Equals str2 (upper/lower case not significant) \IE-str1,str2[macro] Do macro only If str1 does not Equal str2 \IF+string[macro] Do macro only If string Found on current line or on line above \IF-string[macro] Do macro only If string not Found on current line or on line above \II+string1,string2[macro] Do macro only If string1 is found as a substring Inside string2 \II-string1,string2[macro] Do macro only If string1 is not found as a substring Inside string2 5.7: BOYAN Power--Macros and Script Files 127 ________________________________________________________________________ \IK+[macro] Do macro only If a Key has been pressed \IK-[macro] Do macro only If no Key has been pressed \IP+c[macro] Do macro only If Protocol c is available \IP-c[macro] Do macro only If Protocol c is not available \IS+x,y,...,z[macro] Do macro only If the current System number is x,y,..., or z \IS-x,y,...,z[macro] Do macro only If the current System number is not x,y,..., or z \IT+[macro] Do macro only If most recent file Transfer was successful \IT-[macro] Do macro only If most recent file Transfer was unsuccessful \IVc+string[macro] Do macro only if variable c (0..9,A..Z) equals string (upper/lower case not significant) \IVc-string[macro] Do macro only if variable c (0..9,A..Z) does not equal string \IW+[macro] Do macro only If last "WF" or other handshaking command was successful \IW-[macro] Do macro only If last "WF" or other handshaking command was unsuccessful \JD Jump to DOS. Requires user to type EXIT to return to BOYAN. \KO[x] Set unattended Keyboard timeOut to x seconds \KS Keep Screen contents in internal buffer and stop displaying incoming data from the modem, until \RS \KVc[string] Read variable x (0..9,A..Z) from keyboard, prompted by string \KVcstring1[string2] Read variable c (0..9,A..Z) from keyboard, prompted by string2 and using string1 as a default \LD+ Log to Disk (using default Log File name) \LD+[filename] Log to Disk using specified filename 5.7: BOYAN Power--Macros and Script Files 128 ________________________________________________________________________ \LD- Turn off logging to disk \LD* Toggle between \LD+ and \LD- \LD*[filename] Toggle between \LD+[filename] and \LD- \LF+ Add LineFeeds to carriage returns \LF- Do not add LineFeeds to carriage returns \LF* Toggle between \LF+ and \LF- \LM[string] Log Message -- insert string into current log file \LVc[] Store the Length of Variable c (0..9,A..Z) in %LV \LVc[x] Set the Length of Variable c (0..9,A..Z) to be exactly x (0..80) characters \MA[x] Do BOYAN MAcro number x (1..120) \MC[x] Set Menu Color to x (1..127) \MVc[y] Set Variable c (0..9,A..z) to the contents of Macro y (1..120) \NC[x] Set Normal text Color to x (1..127) \ND[string] New Drive/Directory \NK+ Turn Numlock ON \NK- Turn Numlock OFF \NK* Toggle Numlock \PA[x] Pause for x (1..32767) seconds \PL Purge line (discard receive buffer) \PM[string] Print message string on printer \PP[x] Select printer port x (1..4) \PR+ Turn printer logging on \PR- Turn printer logging off \PR* Toggle printer logging 5.7: BOYAN Power--Macros and Script Files 129 ________________________________________________________________________ \PS Print Screen \PU[xx:yy] Pause Until specified time (use 24-hour notation) \QA[x] Add entry # x (1..200) to the redialing Queue \QA[###-####] Add the specified phone number to the redialing Queue \QA[string] Add the first dialing directory entry whose name contains string to the redialing Queue \QA+[string] Add every dialing directory entry whose name contains string to the redialing Queue \QA-[x] Delete entry # x (1..200) from the Queue \QA-[string] Delete from the Queue every entry whose name contains string \QC Queue Clear -- wipe out the redialing queue \QD Queue Dial -- redial from queue until connection made \QE Queue -- enter interactive redialing queue \QU[xx:yy] Queue Until -- redial from queue until connecting or time elapses \RB Review Buffer -- enter scroll-back buffer \RC Restore configured normal text Color \RE[macro] REpeat macro indefinitely \REx[macro] REpeat macro, x (1..32767) times \RS Restore screen and re-enable displaying of text from modem (after \KS) \RVc[y] Read Variable c (0..9,A..Z) as input from modem, with a maximum length of y (1..80) characters before carriage return \RVc*[y] Read Variable c (0..9,A..Z) as above, but echo asterisks instead of the actual characters read 5.7: BOYAN Power--Macros and Script Files 130 ________________________________________________________________________ \RVc-[y] Read Variable c (0..9,A..Z) as above, but echo nothing back to the modem \RVc+[y] Read Variable c (0..9,A..Z) as above, with word wrap \RX[-x] Relative X-position; move cursor x columns to the left \RX[x] Relative X-position; move cursor x columns to the right \RY[-y] Relative Y-position; move cursor y rows up \RY[y] Relative Y-position; move cursor y rows down \SB Send modem Break signal \SC[filename] Invoke script (.BSC extension optional) as subroutine \SC[filename;label] Invoke specified block from specified script as subroutine \SK+ Select Secondary Keyset (turn scroll lock ON) \SK- Deselect Secondary Keyset (turn scroll lock OFF) \SK* Toggle Secondary Keyset (toggle scroll lock) \SL[x] Set Line pacing to x (0..255) milliseconds \SMx[string] Set BOYAN Macro x (1..120) to string \SN[string] Display string on right side of status line (where the System Name is usually displayed) \SP[x] Set character Pacing to x (0..255) milliseconds \SS Save current Screen image to the screen dump file \ST[string] Display string on STatus line \SVc[string] Set variable c (0..9,A..Z) to string \TMx[string] Set secondary/Terminal keyset Macro x (41..110) to string \TO[x] Set handshake TimeOut to x (0..255) seconds 5.7: BOYAN Power--Macros and Script Files 131 ________________________________________________________________________ \TR+ Turn on TRace mode \TR- Turn off TRace mode \TR* Toggle TRace mode \TT+ Turn Translation/filter Table on \TT- Turn Translation/filter Table off \TT* Toggle Translation/filter Table \TVc[y] Set variable c (0..9,A..z) to the contents of secondary/Terminal keyset Macro y (41..110) \UF+ Usage log File on (using default usage log filename) \UF+[filename] Turn on Usage log File specified by filename \UF- Usage log File off \UF* Toggle Usage log File \UL[] UpLoad file, prompting for protocol and filename \ULc[] UpLoad file using specified protocol c \UL[filename] UpLoad specified file using default protocol, prompting for confirmation \UL-[filename] UpLoad file using default protocol immediately, bypassing all prompts \ULc[filename] UpLoad specified file using protocol c, prompting for confirmation \ULc-[filename] UpLoad specified file using protocol c, bypassing all prompts \UM[string] Enter Usage Message string into usage log file (if usage file is on) \UNstring[macro] Repeatedly execute macro UNtil string arrives from modem \UTxx:yy[macro] Repeatedly execute macro Until specified Time (24- hour notation) 5.7: BOYAN Power--Macros and Script Files 132 ________________________________________________________________________ \WF[] Wait For any character to arrive from modem \WF[string] Wait For string to arrive from modem \WL Wait for new Line \WP[x] Wait for a Pause of x seconds in the remote system's input \WW+ Automatic Word-Wrap detection for Message Uploads on \WW- Automatic Word-Wrap detection for Message Uploads off \WW* Toggle between \WW+ and \WW- \XX+ Use Xon/Xoff handshaking \XX- Do not use Xon/Xoff handshaking \XX* Toggle between \XX+ and \XX- \ZS Zap (clear) Screen \+Vc[y] Numerically adds y to the contents of variable c (0..9,A..Z). \+Vc[-y] Numerically subtracts y from the contents of variable c (0..9,A..Z). Appendix A HELP! Common Questions & Answers A.1 Modem Questions Q. "Why doesn't BOYAN dial my modem properly?" A. BOYAN comes preset for Hayes-style modems that dial using the ATDT command. If you have a Hayes but wish to use pulse dialing rather than touch-tone, change this command to ATDP@SF{ . To set BOYAN for another kind of modem, consult your modem's manual and set the options in Config Area <M> accordingly. Q. "BOYAN says `dial despite carrier' every time I dial, and it always thinks the modem is connected. Why?" A. BOYAN depends on your modem to give accurate carrier status in the "modem status register." You may have to flick a toggle switch (USR Courier) or type a modem command (Hayes, section 2.3.2) to get this to work properly. As a last resort, try resetting the "Carrier Detect Mask" in Config Area <E> (see section 3.8). If your modem simply cannot be made to reflect the carrier signal properly, then you can disable the "dial despite carrier" message by setting option H to NO in Config Area <E>. Q. "When I start BOYAN, all of BOYAN's commands seem to work properly, but I can't get any response from my modem. What's going on?" A. The most likely problem is that you have selected the wrong modem serial device (port). Press <Alt-P> to select a new serial port (Com1, Com2, Com3, or Com4). Com1 is the first standard serial port, which is built-in on many computers. Com2 is the second port, usually used by internal modems or add-on serial cards. Com3 and Com4 are non-standard ports which may be used if neither Com1 nor Com2 is available for your modem. If using Com3 or Com4, you MUST explicitly configure the port "addresses" as explained in sections 3.2 and 3.8. The modem might also appear "dead" if you have configured CTS/RTS flow control ON (in Config Area <E>), when your modem does not in fact support CTS/RTS flow control. In that case, turn flow control OFF. If you have selected the Host Mode's "Local Test" setting, then BOYAN will not send any information to the modem. Press <Alt-A> to select a new Action Module; the HOST BAM should be used only while the Host Mode script file is running. Q. "How does BOYAN determine the number of data bits and stop bits to use when communicating?" Appendix A: HELP! Common Questions & Answers 134 ________________________________________________________________________ A. BOYAN automatically uses 8 data bits whenever you select no parity, and 7 data bits with even or odd parity. 1 stop bit is always used. These settings should work for any connection. Q. "What can I do if the communications screen seems to `lock up' in the middle of a session?" A. First, try resetting the comm port by pressing <Alt-P>, <Enter>. If that doesn't work, try pressing <Ctrl-C> or <Ctrl-Q> . A final command to try is <Ctrl-End>, which sends a modem break signal. A.2 DOS Questions Q. "BOYAN reports that it doesn't have enough memory to Jump to DOS and/or use the scroll-back buffer. How come?" A. BOYAN divides all available system RAM between the memory needed for the DOS Shell and the memory used to store scroll-back lines. If you have 256K or less, you may not have enough memory to use both of these features. You can change the way BOYAN partitions your system's memory in Config Area <S> (see section 3.5). Q. "Do I have to CHDIR into the BOYAN directory before running BOYAN?" A. No, not if your version of MS-DOS is numbered 3.0 or higher. Suppose the BOYAN files are stored in your C:\BOY5 directory. You may run BOYAN by simply typing C:\BOY5\BOYAN, no matter which drive and directory are currently logged. Q. "My mouse isn't working properly with BOYAN." A. First check Configuration Area <S>, option <M> to make sure that "Use mouse if detected" is set to YES. If it is but BOYAN still doesn't recognize your mouse, you should consult your mouse manual to make sure your mouse driver is being installed properly, either in your CONFIG.SYS or AUTOEXEC.BAT file. If your mouse driver program is old, it may help to acquire a more recent version. Even if your mouse works in Microsoft Windows(TM) without a driver installed, you still do need to install a mouse driver for non-Windows applications such as BOYAN. A.3 BAM Questions Q. "Help, I'm stuck in DOORWAY mode and I can't get out!" A. You must press <Alt-Equals> to leave DOORWAY mode. All other command key codes, including <F1> and <Alt-X>, are sent directly to the modem instead of being processed by BOYAN. Appendix A: HELP! Common Questions & Answers 135 ________________________________________________________________________ Q. "When I use VT-100 terminal emulation to call up a mainframe, the backspace key doesn't work." A. Most mainframes expect a "DEL" character instead of the normal <Ctrl-H> backspace. In BOYAN, press the <Del> key to send the "DEL" character. You may also swap the Backspace and Del keys, in Configuration Area <A>. Q. "Sometimes, when I select a terminal emulation, BOYAN's command keys don't work." A. The terminal emulation BAM's provide secondary definitions for all the cursor keys and function keys. While <Scroll Lock> is locked, these secondary definitions override BOYAN's normal key definitions. Turn <Scroll Lock> OFF to use BOYAN's regular keyset. Q. "How can I link my computer with a friend's, to chat by modem?" A. One way is to use BOYAN's Host Mode, as described in section 4.8. An alternative is to call by voice first. Both of you should press <Alt-A> G to select the "Gossip" BOYAN Action Module. Also, press <Alt-P> to verify that both you and your friend have selected the same speed and parity parameters. Finally, one of you should type ATA <Enter> while the other types ATD <Enter>. After the "CONNECT" messages appear, hang up the (voice) telephone. You should then be able to type back and forth to each other or even transfer files if one party uploads and the other downloads. A.4 File Transfer Questions Q. "ASCII uploads are producing garbled results." A. BOYAN may be sending characters too fast for your modem (or the receiving modem) to handle them. In that case, try increasing the Pacing settings in Configuration Area <E>, options <A> and . Q. "When I do a Zmodem download, the file size isn't captured properly in the BOYAN.USE usage log." A. DSZ, the Zmodem driver program, logs usage information to the file specified by the DSZLOG environment variable. To make DSZ log Zmodem transfer information to the BOYAN.USE file, add the line SET DSZLOG=drive:\path\BOYAN.USE to your AUTOEXEC.BAT file. Appendix A: HELP! Common Questions & Answers 136 ________________________________________________________________________ A.5 Macro Questions Q. "Can I get BOYAN to... ... clear the screen automatically before dialing?" ... automatically return to the dialing directory after I disconnect?" ... display the current time of day with a keypress?" ... run my favorite DOS program with the touch of a key?" ... toggle in and out of Gossip Mode by pressing <Alt-G>?" A. Yes, using BOYAN's Macro language. These and many other examples are explained in section 5.3. Q. "I wrote a new BOYAN start-up macro #9 (or any other BOYAN macro), but it's too long to fit in the 80-character space provided." A. The solution is to break the macro in half. Save the second half of the macro in an unused BOYAN macro--say, #60 (the <Ctrl-@> keystroke macro). Then save your macro's first half in its normal place, macro #9, but append the command \MA[60]. When the \MA[60] command is reached, macro #60 will be executed, completing your long macro. Q. "Is there any way to restore the original 120 BOYAN Macros?" A. Just delete the BOYAN.MAC file from your disk before entering BOYAN. When you run BOYAN, the original BOYAN.MAC will be recreated. A.6 Miscellaneous Q. "BOYAN came packaged with my brand-new $200 modem. Why do I have to pay any more to use it?" A. BOYAN Communications receives absolutely no compensation from the modem manufacturers. Please see section 1.2 for information about the ShareWare system. Q. "How can I find out about new terminal emulations, enhancements, and upgrades to BOYAN 5?" A. The BOYAN Support BBS always carries the latest version of BOYAN, including the most recent Action Modules, script files, etc. Registered users will be notified about major upgrades by mail. Q. "What if I like BOYAN but need specific changes? Can I have the welcome screen customized for my corporation?" A. Although BOYAN's source code is not available, we will gladly try to incorporate specific changes for out-of-the-ordinary communications needs. A customized welcome screen is available to any corporation that licenses seven or more copies of BOYAN, as described in section 1.2.2. Appendix B BOYAN Error Messages - "BOYAN cannot fit in the available memory!" In this case, perhaps you can make more room for BOYAN by rebooting without installing any memory-resident programs. BOYAN has minimal memory requirements, so this condition should be rare. - "Com1 not ready! Use Com2?", etc. If BOYAN detects a problem while initializing the serial port, it will give you the chance to specify a different port before entering the program. Press N to go ahead and try to use the port which is not ready, or press Y to use the alternate port BOYAN offers. - "Endless loop." Because of memory limitations, recursive nesting in a macro or script cannot exceed approximately 20 levels of depth. If it ever does, BOYAN reports this error message. In a script, this message might indicate that you have used the \BL[..] (call block recursively) command where you should have used the \GB[..] (Goto Block) command. - "No memory for DOS Shell!" This message probably means that you have run BOYAN from within too small a DOS shell. For a discussion of BOYAN's memory handling, please see section 3.5. - "Overlay not found!", "BOYAN.HLP not found!", or "Couldn't load any Action Module!" These errors will occur if the necessary BOYAN auxiliary files are not located in the current DOS directory. - "Serious module malfunction." This ominous message indicates that the BAM file you chose is not a valid Action Module for BOYAN 5. - "Unable to create BOYAN.FON!", "Unable to create BOYAN.MAC!", "Unable to create BOYAN.CNF!" Probable causes of these messages are either 1) Your disk is write-protected, or 2) Your disk is full. The required BOYAN files will fit on a single diskette with room to spare. - "Unknown variable %XY", "Unknown command \XY", "\XY command syntax error", "\XY expects +,-,or *". The macro command compiler reports these basic error conditions. Macro processing stops after such an error. Appendix C Glossary of BOYAN Terms The following few definitions--some standard "computerese", some specific to the BOYAN program--will be useful as you start out with BOYAN: Action Module general name for files telling BOYAN "how to act"--how to interpret what you type, and how to interpret what the remote system sends back. There is exactly one Action Module active at all times. Terminal emulations, gossip mode, and host mode are all examples of BOYAN Action Modules. BOYAN stores its Action Modules in files with the ".BAM" suffix. carrier signal the signal that your modem should send to BOYAN whenever it is connected to another system. Also called the CD (Carrier Detect) signal. default the value something gets if you don't specifically change it. For example, the first time you run BOYAN, all options are set to their default values. Similarly, at most BOYAN prompts, BOYAN provides a default answer which you may select by simply pressing <Enter> or clicking your mouse's left button. downloading receiving a DOS file from the remote system, via your modem. keyset the keyboard's function keys and cursor keys, along with the BOYAN commands they perform. Many terminal emulations have a "secondary keyset" which allows those keys to act as special terminal keys, as well as normal BOYAN command keys. macro a line of BOYAN instructions. If you know in advance what you want BOYAN to do, you can put your instructions into a macro, and then run that macro later with a single keystroke. BOYAN's powerful macro language is the key to its unmatched flexibility. Appendix C: Glossary of BOYAN Terms 139 ________________________________________________________________________ overlay the BOYAN.000 through BOYAN.006 files on your BOYAN disk. Never remove the disk containing these files while BOYAN is running. protocol any of the methods available for uploading and downloading files. The best protocols use error- checking to guarantee file integrity without sacri- ficing transmission speed. Some protocols, such as Zmodem and Kermit, are "external," meaning they require a supplemental program on your disk in order to work with BOYAN. remote system who's on the other end of the modem connection. Databases and bulletin board systems are examples of remote systems. script file a text file consisting of multiple macros. If you plan carefully, a script file can be used to automate complex communications chores, even when the computer is unattended. BOYAN script filenames have a suffix of ".BSC". terminal emulation Mainframe computers normally expect to be used via special "smart terminals," which interpret the mainframe's display output, and also send special key sequences back. BOYAN's emulations allow your computer to mimic such a terminal. terminal mode BOYAN's normal mode of operation, in which all text arriving from the modem is displayed on your screen, and all keys you press (except for BOYAN commands) are sent out over the modem. Sometimes this is also called BOYAN's "Communications ready" screen. uploading sending a DOS file to the remote system, via your modem. Appendix D The VT-100 Secondary Keyset D.1 Default Key Layout When using any terminal emulation, you must press the <Scroll-Lock> key to activate its "secondary keyset." The Status Line displays a small 2 to indicate that the secondary keyset is in use. BOYAN's VT-100 keyset is tailored to the Emacs editor used on most mainframes. When <Scroll-Lock> is locked, the following key definitions take effect: BOYAN Key EMACS Function BOYAN Key EMACS Function <Left-Arrow> left 1 character <Ctrl-Left> left 1 word <Right-Arrow> right 1 character <Ctrl-Right> right 1 word <Up-Arrow> up 1 line <Down-Arrow> down 1 line <Ins> toggle insert mode <Home> to start of line <F3> set mark <End> to end of line <F4> copy region <PgUp> scroll back 1 page <F5> delete region <PgDn> scroll fwd 1 page <F6> yank region <Ctrl-Home> to start of buffer <F9> scroll up 1 line <Ctrl-End> to end of buffer <F10> scroll down 1 line <Ctrl-PgUp> PgUp other window <Ctrl-F9> F9 other window <Ctrl-PgDn> PgDn other window <Ctrl-F10> F10 other window The secondary keyset also makes use of the IBM-PC's function keys to emulate the VT-100's numeric keypad. The following chart illustrates how your 10 Alt-function keys and 10 Shift-function keys correspond to the 18 keys of the VT-100 keypad: Appendix D: The VT-100 Secondary Keyset 141 ________________________________________________________________________ BOYAN Function Keys VT-100 Keypad <AF1> - <AF10> <SF1> - <SF10> +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ |PF1 | |PF2 | |PF3 | |PF4 | |PF1 | |PF2 | |PF3 | |PF4 | +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ | 7 | | 8 | | 9 | | - | | 7 | | 8 | | 9 | | - | +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ | 4 | | 5 | | 6 | | , | | 4 | | 5 | | 6 | | , | +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+ | 1 | | 2 | | 3 | |ENT | | 1 | | 2 | | 3 | | | +----+ +----+ +----+ +----+ +----+ +----+ +----+ | E | +----+ +----+ +----+ +----+ +-----------+ +----+ | N | | 0 | | 0 | | . | |ENT | | 0 | | . | | T | +----+ +----+ +----+ +----+ +-----------+ +----+ +----+ D.2 Customization The standard mapping of the function keys may be modified in any way you find convenient. Here's how to customize the VT-100 secondary keyset: 1. Type <Alt-C> A to enter Configuration Area <A>: Action Modules. 2. Type C 1 to select VT-100 as the current action module, if it is not already current. 3. Press E to begin editing the VT-100 secondary keyset. You will be presented with a menu of the 70 user-definable keystroke macros, separated into seven ranges of ten macros each. 4. Press the key which you want to re-assign, e.g. <Alt-F1>. (If you prefer, you may first press a letter from E-J to display a range of ten keystroke macros, and then select the key to be re- assigned.) 5. In the table below, look up the VT-100 key which you would like to bind to Alt-<F1> (or whatever key you have chosen). Type in the BOYAN macro associated with that VT-100 key, exactly as shown in the table, and press <Enter>. Your new key assignment is saved to the VT-100.CNF file on disk. 6. Repeat these last two steps until the secondary keyset is arranged precisely to your liking! Appendix D: The VT-100 Secondary Keyset 142 ________________________________________________________________________ VT-100 Key BOYAN Macro VT-100 Key BOYAN Macro <PF1>-Gold ^[OP Keypad 0 ^[Op <PF2>-Help ^[OQ Keypad 1 ^[Oq <PF3>-Next ^[OR Keypad 2 ^[Or <PF4>-DelBrk ^[OS Keypad 3 ^[Os Keypad 4 ^[Ot <Up-Arrow> ^[[A Keypad 5 ^[Ou <Down-Arrow> ^[[B Keypad 6 ^[Ov <Right-Arrow> ^[[C Keypad 7 ^[Ow <Left-Arrow> ^[[D Keypad 8 ^[Ox Keypad 9 ^[Oy Backspace DEL \CH[127] Keypad - ^[Om Keypad <Enter> ^[OM Keypad , ^[Ol Keypad . ^[On Index 16550AN UART 84 Alt-T 40 43-line mode 40 Alt-U 61 \\ macro comment 100 Alt-V 65, 105 \+V macro command 100 Alt-W 65, 105 @ variable prefix 116 Alt-X 40 1K-Xmodem 55 Alt-Y 65 Alt-Z 41 A alternate dialing command 19, 30 \AB macro command 100 \AM macro command 84 Action Module 33, 52, 138 %AM macro variable 84 default 33 %AN macro variable 84 \AD macro command 88 %AP macro variable 84 address 7 arithmetic 100 ADM-3A 53 ASCII 56 \AF macro command 94 \AT macro command 100 \AL macro command 90 %AU macro command 96 alarm 51 %AU macro variable 96 level 20 auto-downloading 38, 57 Alt-Equals 52 default 25 Alt-A 52 macro 32 Alt-B 40 Auto-find transfer filename 25 Alt-C 16 AUTOEXEC.BAT 135 Alt-D 41, 108 \AV macro command 91 Alt-E 40 Alt-F 61 B Alt-F1 39 \B8 macro command 84 Alt-F10 104 %B8 macro variable 84 Alt-G 40 %B: macro variable 94 Alt-H 49 Backspace 34, 78 Alt-I 73 Backspace Editor 78 Alt-J 64 BAM See: Action Module Alt-K 32 Basic Commands 39 Alt-L 60, 105 batch transfers 57 Alt-M 71 \BB macro command 91 Alt-N 65, 104 \BC macro command 85 Alt-O 40 \BD macro command 84 Alt-P 49 %BD macro variable 84 Alt-Q 50 Beeps & Bells 40 Alt-R 66, 105 default 20 Alt-S 60 Bimodem 56 Index 144 ________________________________________________________________________ \BL script command 111 configuration 16 BOYAN Action Module See: Action dialing 30, 133 Module disk 21 BOYAN.CNF 11 expert communications 26 BOYAN Commands 39 file transfers 21 BOYAN.FON 11, 22 Hayes modem 12 BOYAN.LOG 23 macros 28 BOYAN.MAC 11, 104, 136 memory 134 BOYAN.PWD 11 modem 24 BOYAN Support BBS 7 Practical Peripherals modem BOYAN.USE 23, 61 12 break signal 52, 84, 134 screen 19 \BU macro command 84 USR Courier HST modem 18 %BU macro variable 84 CONTROL Action Module 53 bulk discounts 5 control characters 28 Bulletin Board Systems 53 copying files 63 \BW macro command 85 Copyright 4 Corporate Licenses 5 C \CP macro command 83 %C: macro variable 94 CRC-Xmodem 55 \CA macro command 82 credit card orders 5 Call Data Standard 61 \CS macro command 83 Call Waiting 49 \CT macro command 85 carrier signal 11, 26, 133, 138 Ctrl-Backspace 78 \CB macro command 102 Ctrl-End 52 \CC macro command 88 Ctrl-LeftArrow 78 \CD macro command 83 Ctrl-PgUp 62, 64 Centrex 48 Ctrl-PrtSc 61 \CF macro command 94 Ctrl-RightArrow 78 \CH macro command 83 CTS/RTS flow control 26, 133 change parameters 49 customizing BOYAN 16 character pacing 26 cycle dialing 31, 42 chat mode 54 CIS.BSC 114 D clear screen 41 %D: macro variable 96 \CM macro command 83 %DA macro variable 86 \CO macro command 88 data bits 50, 133 colors 20, 40 \DC macro command 94 customizing 20 \DD macro command 83 Com3 port 27 dedicated printing 54 Com4 port 28 default 138 command line 110 DEL character 34, 52 Command Menu 13, 39, 102 Del key 34, 52 comment deleting files 63 macro 100 DesqView 12 COMMENTS.HOS 74, 76 \DI macro command 88 CompuServe 24, 46, 114 dial despite carrier 27, 133 file transfer 57 dialing 41 conclude macro 31 cycle 31 Index 145 ________________________________________________________________________ modem command 30, 48, 133 emulation See: terminal alternate 19, 30, 45 emulation dialing directory 49 error messages 137 alphabetizing 44 Esc key 13 baud rate fill 44 Escape character 28 codes 42 ETCH.BSC 114 deleting 44 Everfax modems 31 edit entry 45 \EX macro command 102 exchange 48 exiting BOYAN 40, 102 file ASCII copy 23, 46 grab # feature 46 F locate 47 %F: macro variable 88 multiple 47 \FC macro command 85 print 47 \FD macro command 88 Disclaimer 7 %FD macro variable 88 disk logging 23, 60 \FE macro command 95 distribution file listing 65 ShareWare 6 The File Manager 61 \DL macro command 96 sorting 22 \DM macro command 91 file size information 63 %DM macro variable 91 file transfer 55 \DMC macro command 91 auto-find filename 25, 57 %DN macro variable 93 batch 56 DOORWAY.EXE 72, 74 downloading 59 DOORWAY Module 54 directory 22 DOS shell 21, 41, 64, 65 efficiency 60 downloading 138, See Also: file protocols 139 transfer 1K-Xmodem 55 \DP macro command 97 ASCII 56 %DP macro variable 97 batch-Ymodem 56 %DR macro variable 95 Bimodem 56 %DS macro variable 95 Compuserve-B 57 DSZLOG environment variable 135 CRC-Xmodem 55 \DT macro command 83 default 25, 46, 58, 59, 97 DTR signal 11, 26 external 36, 56 DUMBTERM 54 G-Ymodem 56 duplex toggle 40 Kermit 56, 57 \DV macro command 98 Megalink 57 MPt 57 E Relaxed Xmodem 55 \EB script command 111 Sealink 57 \EC macro command 85 Xmodem 55 %EC macro variable 85 Ymodem 55 echo keyboard 40 Ymodem-batch 57 default 24 Zmodem 56, 57 editing files 22, 64, 65 uploading 58, 64 elapsed-time clock 13 directory 22 \EM macro command 100 message 58 Emacs editor 55, 140 file viewing 22 Index 146 ________________________________________________________________________ \FM macro command 95 %IK macro variable 101 FON files 47 %IM macro variable 101 selection 63 initialization string 31 free disk space 25, 64, 65 Ins key 65 \FS macro command 95 installation 9 Function Key Customization 32 Intel modems 19 function key menu 39 \IP macro command 97 \FW macro command 85 IRQ line 28, 83 \IS macro command 89 G \IT macro command 97 G-Ymodem 56 \IV macro command 99 \GB script command 111 \IW macro command 87 \GL macro command 91 %GL macro variable 91 J Glossary 138 \JD macro command 95 gossip mode 54, 109 jump to DOS 21, 41, 64 grab phone # feature 46 graphics symbols 35 K \GS script command 112 Kermit 57 \GV macro command 98 keyboard timeout 27 \GX macro command 91 keyset 138 \GY macro command 91 \KO macro command 112 \KS macro command 92 H \KV macro command 99 handshaking 26 hanging up 30, 49 L \HE macro command 102 %LC macro variable 96 help screens 13 \LD macro command 93 High-Speed Modem 18 %LD macro variable 93 \HK macro command 102 Learn (Script) See: Script Learn HOST.BSC 114 Facility Host Mode 71 LeftArrow 78 configuration 34 \LF macro command 85 HOST.USE 76 %LF macro variable 85 How to Order 5 Licensing 4 %HR macro variable 86 Line Editor 14 \HU macro command 83 line format 50 Line pacing 26 I linefeeds 41 IBM-3101 53 default 25 IBM PS/2 LIST 22 Com3 27 \LM macro command 93 Com4 28 %LN macro variable 93 \IE macro command 101 logon password 21, 46 \IF macro command 86 LOGON script block 112 \II macro command 101 Long-Distance Dialing Prefixes %II macro variable 101 48 \IK macro command 101 \LV macro command 99 Index 147 ________________________________________________________________________ M Mouse click macro 31 \MA macro command 101 mouse interface 13, 21, 43, 51, %MA macro variable 83 63, 67 macro 28, 71, 138 MPt protocol 57 basic form 28 Shortcut 30, 48 N variables 117 \NC macro command 92 macro commands %NC macro variable 92 dialing 88 \ND macro command 96 DOS 94 new drive/directory 63, 65 file transfers 96 \NK macro command 103 modem 82 %NK macro variable 103 pausing 86 null modem 72 queue 89 Num-Lock 103 repeat 102 NUMBERS.TXT 23 screen 90 summary 120 O terminal 84 order form 5 timing 86 overlay 139 trace 103 user variables 98 P Macro Programming Language %P: macro variable 97 80-103 \PA macro command 86 Manual Dialing 41 pacing 135 \MC macro command 92 character 26 %MC macro variable 92 line 26 %MD macro variable 83 parameter change 30, 49 Megalink 57 password 46 memory usage 21 default 21 menus Password Security Feature 70 user-defined 92 PCBOARD.BSC 114 Message Upload 56 PgDn 59 %MI macro variable 86 PgUp 58 Microsoft Windows 12 phone call log 61 missing characters 19 phone order line 5 %MN macro variable 83 PKUNZIP 75 MNP 56 \PL macro command 83 configuration 19 \PM macro command 93 %MO macro variable 86 \PP macro command 93 modem break signal See: break \PR macro command 93 signal %PR macro variable 93 modem messages 24 Practical Peripherals 19 modem settings 49 print screen 61 parity 11, 24 printer port 11, 24 dialing directory 47 Com3 27 init macro 32 Com4 28 logging 61 speed 11, 24 scroll-back buffer 67 Modem Setup 11 printing files 63 Index 148 ________________________________________________________________________ protocol See: file transfer examples 114 Protocol disk 18 logon 112 \PS macro command 93 running 63, 66, 113 \PU macro command 86 Script Learn Facility 68 pulse dialing 17 Quick-learn 68 purchase orders 6 SCRNDUMP.TXT 23 %PW macro variable 89 scroll-back buffer 21, 23, 66 PWD file 46 Scroll-Lock 53, 102 %SE macro variable 86 Q SEAlink 57 Q-time 50 secondary keyset 13, 53 \QA macro command 89 Session Logging 60 \QC macro command 90 %SF macro variable 89 \QD macro command 90 ShareWare 6 \QE macro command 90 distributors 6 %QS macro variable 90 Shift-PrtSc 61 \QU macro command 90 Shift-Tab 41 Questions & Answers 133 shipping 5 queue redialer 50 Shortcut macros 30, 48 Quick-learn script 68 site licenses 5 Quick Reference Card 5 \SK macro command 102 %SK macro variable 102 R \SL macro command 86 RAM-resident programs 19 %SL macro variable 89 \RB macro command 102 \SM macro command 103 \RC macro command 92 \SN macro command 92 \RE macro command 102 %SN macro variable 89 registration 4 sound effects 20, 40 Relaxed Xmodem 55 \SP macro command 86 remote system 139 \SS macro command 93 renaming files 64 %SS macro variable 89 Restore Default Text Color 40 \ST macro command 92 <Return> character 29 start-up 11 RightArrow 78 start-up macro 31 \RV macro command 99 Status Line 12 \RX macro command 92 stop bits 50, 133 \RY macro command 92 strip 8th bit 36 Support 7 S \SV macro command 100 %S# macro variable 89 system requirements 9 %S: macro variable 112 memory 21 \SB macro command 84 %SC macro variable 112 T \SC script command 112 %T: macro variable 97 SCRBACK.LOG 23 Tab key 114 screen dump 23, 60 Tandy computers 53 script files 111, 139 TCOMM.BSC 114 blocks 111 TED 22 directory 23 Index 149 ________________________________________________________________________ terminal emulation 34, 53, 139 V secondary keyset 13, 53 %V0 macro variable 98 VT-100 54, 140 variables terminal keyset 53 @ vs. % prefixes 116 terminal mode 12, 139 summary 117 %TF macro variable 97 VARS.BSC 115 %TI macro variable 97 viewing files 22, 64, 65 timeout VT-52 53 default 27 VT-100 action module 54, 140 \TM macro command 103 \TO macro command 87 W \TR macro command 103 %WC macro variable 96 trace mode 103 welcome screen 11 translation table 40 customization 6 \TT macro command 85 \WF macro command 87 %TT macro variable 85 Windows 12 \TV macro command 100 \WL macro command 87 TVI-925 53 word length 24 typography 7 word processor 22, 65 word wrap auto-detection 25, 59 U \WP macro command 87 %U: macro variable 96 *WRAPUP block 114 UART \WW macro command 98 16550AN 84 %UD macro variable 98 X \UF macro command 94 Xmodem 55 %UF macro variable 94 XON/XOFF flow control 26 \UL macro command 98 %XP macro variable 92 \UM macro command 94 \XX macro command 85 \UN macro command 87 %UN macro variable 94 Y unattended 114 Ymodem 55 Uniform Dialing Prefixes 48 Ymodem-batch 57 Unix 55 %YP macro variable 92 UpArrow 66 %YR macro variable 86 uploading 139, See Also: file transfer Z usage log file 23, 61 zap screen 41 macros 94 ZIP files 9, 75, 109 Zmodem transfers 135 Zmodem 57 Users Groups 6 usage log 135 USR Courier HST 18 \ZS macro command 93 \UT macro command 86 About the Author Justin Boyan was born in 1970 in State College, Pennsylvania. He grew up in Columbia, Maryland, where his favorite hobbies were swimming, playing the piano, and later, computer programming. His interest in computers began when he discovered his school's TRS-80 in the sixth grade ("I loved working with it, except for the time I accidentally blew up a disk drive"). He taught himself BASIC, and later learned Pascal as a student at Johns Hopkins University's Center for Talented Youth summer program. Since age 16, he has returned to CTY each summer as a member of the mathematics teaching staff. In 1987, he graduated first in his class from Oakland Mills High School, where he was on the Math Team, Tennis Team, and state champion Computer Team. BOYAN Communications was conceived when Justin was in the ninth grade, shortly after his family acquired a modem. With a vision of what the "ideal communications software" would be and the encouragment of several local Sysops, he began creating the program. BOYAN version 1 was released as ShareWare in October 1986. Further revisions were released in 1987 and 1989, as he continued perfecting the program during college. In 1991, he received his Bachelor of Science degree in mathematics from the University of Chicago. His honors there included election to Phi Beta Kappa and the Cohen Memorial Prize for highest academic record in the field of mathematics. He also moonlighted as pianist for the campus comedy troupe. For the 1991-92 academic year, he has been awarded the Winston Churchill Scholarship for study at Cambridge, where he will earn an M. Phil. in Computer Speech and Language Processing. He will continue his education at Carnegie Mellon University, working toward a Ph.D. in Computer Science.